AI Agent

License: MIT

Jenkins Plugin

Jenkins 플러그인으로, Jenkins job과 pipeline에서 자율 코딩 에이전트(Claude Code, Codex CLI, Cursor Agent, OpenCode, Antigravity CLI, Gemini CLI, Grok Build, Pi, Oh My Pi, Kiro CLI)를 실행하기 위한 재사용 가능한 Run AI Agent 빌드 단계를 추가합니다.

플러그인 ID (artifactId): ai-agent

기능 (Features)

• 재사용 가능한 빌드 단계 (Reusable build step) — Freestyle job 또는 Pipeline에서 aiAgent(...)를 통해 Run AI Agent 추가 가능.
• 다중 에이전트 지원 (Multiple agent support): Claude Code, Codex CLI, Cursor Agent, OpenCode, Antigravity CLI, Gemini CLI, Grok Build, Pi Coding Agent, Oh My Pi (OMP), Kiro CLI.
• 인라인 대화 보기 (Inline conversation view) — 빌드 페이지에서 어시스턴트 메시지, 입력/출력과 함께 도구 호출(tool calls)의 구조적 표시 및 사고 과정 블록을 실시간 스트리밍으로 확인. 동일 빌드 내 여러 호출은 별도의 카드(최신 확장, 이전 축소 가능)로 표시됨.
• 마크다운 렌더링 (Markdown rendering) — 어시스턴트 및 결과 메시지가 포맷된 HTML로 렌더링됨.
• 승인 게이트 (Approval gates) — 도구 실행 전에 수동 검토를 위해 빌드를 선택적으로 일시 중지할 수 있음.
• 사용 통계 (Usage statistics) — 에이전트 로그에서 토큰 수, 비용 및 지속 시간을 추출하여 빌드별로 표시함.
• Codex 제어 기능 (Codex controls) — job 범위의 ~/.codex/config.toml, 전역 Codex 인자(args), 그리고 Codex 실행을 위한 codex exec 인자가 제공됨.
• 표준 Jenkins 통합 (Standard Jenkins integrations) — SCM 체크아웃, 빌드 트리거, 자격 증명 주입(credentials injection), 빌드 후 셸 단계(post-build shell steps), 및 퍼블리셔 지원.

지원 에이전트 (Supported Agents)

스크린샷

도구 호출, 마크다운 렌더링된 응답 및 사용 통계가 포함된 Cursor Agent 대화가 표시되는 빌드 페이지:

설치 (Installation)

옵션 1: Jenkins 플러그인 센터에서 설치 (권장)

1. Jenkins에서 Manage Jenkins > Plugins로 이동합니다.
2. Available plugins 탭을 엽니다.
3. AI Agent를 검색합니다 (플러그인 ID: ai-agent).
4. 플러그인을 설치하고, 요청 시 Jenkins를 재시작합니다.

옵션 2: .hpi 파일을 사용한 오프라인/수동 설치

1. 플러그인을 빌드하거나 ( Building 참조) 배포용 릴리스 .hpi 파일을 다운로드합니다.
2. Manage Jenkins > Plugins > Advanced settings로 이동합니다.
3. Deploy Plugin 아래에 .hpi 파일을 업로드합니다.
4. Jenkins를 재시작합니다.

빠른 시작 (Quick Start)

1. Jenkins 작업(Job)을 생성하거나 엽니다 (Freestyle 또는 Pipeline).
2. Run AI Agent 빌드 단계를 추가/구성합니다:
   • Agent Type: 실행할 코딩 에이전트를 선택합니다.
   • Prompt: 에이전트에게 보낼 작업 내용입니다.
   • Model: 선택적 모델 재정의(override) 값입니다. Codex, Claude Code, OpenCode는 model:effort과 같은 간략한 구문(gpt-5.6-sol:xhigh)을 허용하며, Antigravity CLI와 Grok Build는 low, medium, 또는 high를 허용합니다 (예: gemini-3.6-flash:high 또는 grok-4.5:high).
   • Reasoning effort: 지원되는 에이전트의 선택적 노력(effort) 재정의 값입니다 (예: high, xhigh); 모델 접미사보다 우선합니다.
   • YOLO mode: 에이전트에서 확인 프롬프트를 건너뜁니다.
   • Approvals: 도구 호출에 대한 사람의 승인을 요구합니다.
   • Setup script: 에이전트 실행 전에 실행할 셸 명령어입니다 (도구 설치, dotfiles 소싱, 런타임 변수 구성 등).
   • Custom Codex config.toml: 선택적이며, 작업별 설정/MCP를 재정의하기 위해 Codex 실행 시에만 표시됩니다.
   • Additional Codex args: 선택적이며, --search와 같은 전역 플래그나 --ignore-user-config와 같은 실행 플래그를 전달하기 위해 Codex 실행 시에만 표시됩니다.
   • Environment variables: 추가 환경 변수를 주입합니다 (KEY=VALUE, 줄마다 하나씩).
   • Command override: 기본 명령어 템플릿을 완전히 대체합니다.
   • Extra CLI args: 생성된 명령어에 플래그를 추가합니다.
3. 선택적으로 SCM, 빌드 트리거, 후속 빌드 단계(post-build steps), 게시자(publishers) 등을 다른 Jenkins 작업과 마찬가지로 추가합니다.
4. 작업을 빌드합니다. 대화 내용은 빌드 페이지에서 실시간으로 스트리밍됩니다.

파이프라인 구문

단계(step) 심볼은 aiAgent이며, 에이전트 핸들러는 claudeCode(), codex(), cursor(), openCode(), antigravity(), geminiCli(), grok(), pi(), omp(), kiro()와 같은 심볼로 참조됩니다.

최소 호출 (기본 Claude Code 핸들러 사용):

aiAgent(
  prompt: '이 저장소를 요약하고 정리할 PR 3개를 제안하세요'
)

모델 고정 및 추론 노력(reasoning effort)을 갖춘 Antigravity CLI:

aiAgent(
  agent: antigravity(),
  prompt: '이 프로젝트를 검토하고 실패하는 테스트를 수정하세요',
...

Gemini CLI에서 Antigravity CLI로 전환하기

Google은 Gemini CLI 사용자를 Antigravity CLI로 전환하고 있습니다.
이 플러그인은 geminiCli()를 유지하여, 구성 변경 없이 작업이 독립적으로 마이그레이션될 수 있도록 합니다.

각 Jenkins 노드에 공식 Antigravity 설치 프로그램을 설치하고, 해당 디렉터리가 Jenkins 서비스 계정의 PATH에 포함되도록 하며, 해당 OS 계정으로 한 번 인증해야 합니다. agy 1.1.7 이상 버전을 사용해야 하며, 플러그인 지원은 Antigravity CLI 변경 로그에 문서화된 헤드리스 JSON 출력 및 사용 필드에 의존합니다. 기본 명령어는 --output-format stream-json을 사용하는 헤드리스 --print 모드를 사용합니다.
Antigravity의 --model, --effort, 그리고 --dangerously-skip-permissions 플래그는 플러그인의 Model, Reasoning effort, YOLO 필드에 매핑됩니다. 모델 슬러그가 노력 접미사(effort suffix)를 포함하는 경우, 두 값을 일치하게 유지해야 합니다 (예: gemini-3.6-flash-high와 high).

수동 도구 호출 승인이 있는 OpenCode:

aiAgent(
  agent: openCode(),
  prompt: '파서를 리팩토링하고 테스트를 추가하세요',
...

API 키 인증, 모델/노력 선택 및 수동 도구 호출 승인이 있는 Grok Build:

Codex를 job 스코프의 config.toml과 함께 사용:

aiAgent(
  agent: codex(
    customConfigEnabled: true,
...

API 키 인증 및 신뢰할 수 있는 도구를 갖춘 Kiro CLI 사용:

aiAgent(
  agent: kiro(
  prompt: 'Review the repository and fix the failing tests',
...

Kiro jobs는 kiro-cli chat --no-interactive --output-format stream-json을 사용합니다.
명령어 플래그는 Kiro CLI 2.27.1을 기준으로 검증되었습니다.
YOLO는 이 예시의 수정 및 테스트 실행에 필요한 --trust-all-tools를 추가합니다.
YOLO가 비활성화된 경우, 플러그인은 Kiro가 구성한 도구 권한을 유지합니다.
헤드리스(headless) 리뷰에서 특정 도구 접근이 필요한 경우, --trust-tools=fs_read와 같은 추가 인수를 사용하십시오. 대화형 승인이 필요한 도구 요청은 Jenkins를 통해 승인될 수 없으며, Kiro jobs는 실행 전에 Jenkins의 수동 승인을 거부합니다.
신뢰 옵션에 대해서는 Kiro headless mode를 참조하십시오.

Jenkins는 선택된 자격 증명(credential)을 KIRO_API_KEY로 주입합니다. Kiro의 인증 우선순위(authentication precedence)에 따르면 활성 브라우저 세션이 API 키보다 우선권을 가지므로, 작업이 해당 자격 증명을 사용해야 하는 경우 캐시된 Kiro 로그인이 없는 Jenkins 노드 계정을 사용하십시오.

Pi Coding Agent

Pi jobs를 실행하는 모든 Jenkins 노드에 Node.js 22.19.0 이상 버전과 함께 @earendil-works/pi-coding-agent을 설치하십시오. 명령어와 이벤트 통합은 Pi 0.82.1을 기준으로 검증되었으며, 임시적이고 비대화형 실행을 위해 pi --print --mode json --no-session을 사용합니다.

aiAgent(
  agent: pi(
  prompt: 'Review the repository and report potential bugs',
...

제공자(provider)가 지정된 모델을 사용하거나 Extra args를 통해 --provider를 전달하세요. 별도의 reasoningEffort 필드는 model:effort 접미사를 덮어쓰고 --thinking에 매핑됩니다. 지원되는 레벨은 off, minimal, low, medium, high, xhigh, 그리고 max이며, 모델별로 지원 여부가 다릅니다. Jenkins 자격 증명(credential)에는 OPENAI_API_KEY 또는 ANTHROPIC_API_KEY와 같은 명시적인 제공자 환경 변수가 필요합니다. 사전에 구성된 노드 수준 인증도 Jenkins 자격 증명 없이 작동합니다.

YOLO가 비활성화되면, 명령어는 프로젝트 로컬 설정(--no-approve)을 무시하고 read, grep, find, ls만 활성화합니다. YOLO는 Pi의 기본 도구를 활성화하며 프로젝트 로컬 설정을 신뢰합니다(--approve). 확장 기능(Extension) 검색은 두 모드 모두에서 기본적으로 비활성화되며, 신뢰할 수 있는 작업 작성자(job author)는 Extra args에 -e를 사용하여 확장 기능을 명시적으로 로드할 수 있습니다. 또한 Extra args가 도구 선택을 덮어쓸 수도 있습니다.

이러한 제어 기능은 OS 샌드박스가 아닙니다. 작업을 수행하는 데 필요한 파일과 자격 증명만을 가진 격리된 Jenkins 노드에서 Pi를 실행하세요. Pi는 플러그인의 양방향 승인 채널을 제공하지 않으므로, Jenkins의 수동 승인은 거부됩니다. 이 플러그인은 어시스턴트 텍스트, 사고 과정(thinking), 도구 입력/출력, 토큰 및 비용을 캡처하며, 최종 어시스턴트 오류나 Pi가 종료 코드 0으로 나가더라도 빌드를 실패 처리합니다.

Oh My Pi (OMP)

OMP 작업을 실행하는 모든 Jenkins 노드에 @oh-my-pi/pi-coding-agent를 설치하세요. 공식 Bun 패키지는 Bun 1.3.14 이상을 요구합니다:

bun install -g @oh-my-pi/pi-coding-agent
omp --version

omp가 Jenkins 서비스 계정의 PATH에 있거나, 작업에서 실행 파일 경로를 설정했는지 확인하세요. 내장 CLI 플래그와 JSON 이벤트 파싱은 OMP 18.3.2 기준으로 검증되었습니다. 제공자 인증은 여전히 유효한 Jenkins 자격 증명 또는 노드에서의 OMP 로그인을 필요로 합니다.

aiAgent(
  agent: omp(),
  prompt: 'Review the repository and suggest a focused fix',
... 

OMP는 provider-qualified 모델 식별자를 허용합니다. 추론 노력(Reasoning effort) 필드는 --thinking에 매핑되며, 지원되는 값에는 off, minimal, low, medium, high, xhigh, max, 및 auto가 포함됩니다. Jenkins 자격 증명(credential)을 선택할 때는 예시와 같이 API Key env var override를 구성된 provider가 예상하는 환경 변수로 설정해야 합니다. 기존의 OMP 인증은 Jenkins 자격 증명 없이도 Jenkins 노드에서 사용할 수 있습니다.

YOLO가 꺼져 있을 때, 내장 명령어는 OMP의 read, grep, 및 glob 도구만 활성화하고 --approval-mode write를 설정합니다. YOLO가 켜져 있을 때는 OMP의 기본 도구가 활성화되고 승인 모드(approval mode)는 yolo로 설정됩니다. 확장 기능 검색(Extension discovery)은 두 모드 모두에서 내장 명령어에 의해 비활성화됩니다. 이러한 제어 장치는 OS 샌드박스가 아닙니다. 작업이 필요한 파일과 자격 증명만 있는 격리된 Jenkins 노드를 사용하십시오. 수동 승인(manual approvals)이 활성화되면, 플러그인은 --approval-mode always-ask를 사용하여 OMP의 ACP 명령을 사용합니다. Jenkins는 표준 ACP 권한 요청과 OMP의 네이티브 도구 Approve/Deny 양식을 처리합니다. 임의의 확장 기능 대화 상자와 계획 양식은 실패 시 닫힙니다(fail closed).

Jenkins는 모든 모드에서 OMP의 실행, 출력 및 세션 플래그 외에도 CLI 도움말/버전/내보내기/별칭(alias) 플래그와 --acp-terminal-auth를 예약합니다. 읽기 전용(Read-only) 및 ACP 승인 모드는 또한 --plugin-dir와 같은 승인 모드 및 확장 기능 로딩 플래그도 거부합니다. 읽기 전용 모드는 --tools를 거부하고, ACP 모드는 --config를 거부합니다. YOLO는 OMP 특정 도구, 확장 기능 및 구성 옵션을 허용합니다.

Node.js 버전 고정(Pinning a Node.js Version)

일부 에이전트(Claude Code, Gemini CLI)는 npx를 통해 설치되며 빌드 에이전트에서 Node.js가 필요합니다. 빌드 전반에 걸쳐 특정 Node.js 버전을 잠그려면 NodeJS Plugin을 사용하십시오.
Manage Jenkins > Tools에서 NodeJS 설치를 구성한 다음, 작업의 빌드 환경에서 이를 선택하여 node와 npx가 고정된 버전으로 해석되도록 하십시오.

Grok Build CLI

Grok 작업을 실행하는 각 Jenkins 노드에 Grok Build을 설치합니다:

curl -fsSL https://x.ai/cli/install.sh | bash
grok models

CI의 경우, xAI API 키를 Jenkins Secret Text 자격 증명으로 저장하고 API key credential에서 선택합니다. Grok Build는 이를 XAI_API_KEY로 받습니다. 노드에 캐시된 grok login 세션도 지원되지만, 임시 에이전트(ephemeral agents)의 경우 API 키 자격 증명이 더 이식성이 높습니다. 설정 스크립트에 의해 내보내진 키는 값 노출 없이 셸 초기화 후에 감지됩니다.

일반 작업은 제한 없는 YOLO 모드 없이 보호된 자동화를 위해 --permission-mode auto를 사용합니다: