도구 구성

도구 구성 (Tool Configuration)

내장 도구, MCP 도구, Docker 기반 도구를 구성하는 완전한 참조 문서예요.

출처: 문서

본문

내장 도구, MCP 도구, Docker 기반 도구를 구성하는 완전한 참조예요.

내장 도구 (Built-in Tools)

내장 도구는 Docker Agent에 포함되어 있고 외부 의존성이 필요 없어요. 에이전트의 toolsets 목록에 type별로 추가하면 돼요. 각 도구의 전용 페이지가 전체 구성 옵션, 사용 가능한 작업, 예제를 다뤄요.

Type	설명	페이지
`filesystem`	읽기, 쓰기, 목록, 검색, 탐색	Filesystem
`git`	읽기 전용 저장소 조사(status, log, branches, show, blame)	Git
`shell`	셸 명령 동기 실행	Shell
`background_jobs`	장수 셸 명령 실행·관리	Background Jobs
`scheduler`	특정 시간 또는 반복 간격으로 실행할 지시 예약	Scheduler
`think`	추론 스크래치패드	Think
`plan`	멀티 에이전트 협업을 위한 공유 영구 스크래치패드	Plan
`session_plan`	draft-review-execute 워크플로우용 세션별 마크다운 플랜	Session Plan
`session_context`	이전 세션을 컨텍스트로 참조(읽기 전용)	Session Context
`todo`	작업 목록 관리	Todo
`memory`	영구 키-값 저장(SQLite)	Memory
`tasks`	세션 간 공유되는 영구 작업 데이터베이스	Tasks
`fetch`	text/markdown/html 출력이 있는 HTTP GET 요청	Fetch
`script`	커스텀 셸 스크립트를 도구로	Script
`lsp`	Language Server Protocol 통합	LSP
`api`	커스텀 HTTP API 도구	API
`openapi`	OpenAPI 3.x 문서의 모든 작업을 도구로 가져오기	OpenAPI
`rag`	인덱싱된 소스에 대한 검색 증강 생성	RAG
`model_picker`	에이전트가 턴마다 여러 모델 중에서 고르게 하기	Model Picker
`user_prompt`	대화형 사용자 입력	User Prompt
`open_url`	사용자 기본 브라우저에서 고정 URL 열기	Open URL
`transfer_task`	서브 에이전트에 위임(자동 활성화)	Transfer Task
`background_agents`	병렬 서브 에이전트 디스패치	Background Agents
`webhook`	재시도가 있는 구성된 목적지로의 신뢰할 수 있는 알림(Slack, Discord, Telegram, IFTTT, Teams, …)	Webhook
`handoff`	같은 구성에서 다른 에이전트로의 로컬 대화 전환(`handoffs:`로 자동 활성화)	Handoff
`a2a`	A2A 원격 에이전트 연결	A2A
`mcp_catalog`	Docker MCP Catalog에서 원격 MCP 서버를 온디맨드로 발견·활성화	MCP Catalog

예제:

toolsets:
- type: filesystem
- type: shell
- type: background_jobs
- type: think
- type: todo
- type: memory
  path: ./dev.db

MCP 도구 (MCP Tools)

Model Context Protocol로 외부 도구로 에이전트를 확장해요. mcp toolset의 독립형 개요는 MCP 도구 페이지를 보세요.

팁 — 재사용 가능한 MCP 정의: 반복되는 MCP 서버 정의는 최상위 mcps: 섹션으로 끌어올릴 수 있고 {type: mcp, ref: <name>}로 이름 참조할 수 있어요. Reusable MCP Servers 참조.

Docker MCP (권장)

MCP Gateway를 통해 MCP 서버를 안전한 Docker 컨테이너로 실행해요:

toolsets:
- type: mcp
  ref: docker:duckduckgo # web search
- type: mcp
  ref: docker:github-official # GitHub integration

사용 가능한 도구는 Docker MCP Catalog에서 확인할 수 있어요.

속성	타입	설명
`ref`	string	Docker MCP 참조(`docker:name`)
`tools`	array	선택: 이 도구들만 노출
`instruction`	string	에이전트 컨텍스트에 주입되는 커스텀 지시
`config`	any	MCP 서버별 구성(초기화 중 전달)
`working_dir`	string	MCP 게이트웨이 서브프로세스의 작업 디렉토리. 카탈로그 항목이 로컬 프로세스로 실행될 때만 적용돼요(원격 아님). 상대 경로는 에이전트 작업 디렉토리 기준으로 해석돼요. `${env.VAR}`(표준), `~` 및 셸 스타일 `$VAR` / `${VAR}` 확장을 지원해요.

로컬 MCP (stdio)

MCP 서버를 stdin/stdout을 통해 통신하는 로컬 프로세스로 실행해요:

toolsets:
- type: mcp
  command: python
  args: [ "-m", "mcp_server" ]
  tools: [ "search", "fetch" ]
  env:
    API_KEY: value

속성	타입	설명
`command`	string	MCP 서버를 실행할 명령
`args`	array	명령 인자
`tools`	array	선택: 이 도구들만 노출
`env`	object	환경 변수(키-값 쌍)
`working_dir`	string	MCP 서버 프로세스의 작업 디렉토리. 상대 경로는 에이전트 작업 디렉토리 기준. 생략하면 에이전트 작업 디렉토리로 기본 설정. `${env.VAR}`(표준), `~` 및 셸 스타일 `$VAR` / `${VAR}` 확장 지원.
`instruction`	string	에이전트 컨텍스트에 주입되는 커스텀 지시
`version`	string	명령 바이너리를 자동 설치하기 위한 패키지 참조

원격 MCP (Streamable HTTP / SSE)

네트워크를 통해 MCP 서버에 연결해요:

toolsets:
- type: mcp
  remote:
    url: "https://mcp-server.example.com"
    transport_type: "streamable"
    headers:
      Authorization: "Bearer your-token"
    # Optional: allow OAuth helper requests to reach private/internal IPs.
    allow_private_ips: true
  tools: [ "search_web", "fetch_url" ]

속성	타입	설명
`remote.url`	string	MCP 서버 URL. `https://`, `http://`, `unix://`(Unix 도메인 소켓) 스킴을 받아들여요.
`remote.transport_type`	string	`streamable` 또는 `sse`
`remote.headers`	object	모든 요청에 보내는 HTTP 헤더. 값은 요청별로 해석되는 `${env.VAR}`와 `${headers.NAME}` 플레이스홀더를 지원해요. `${env.VAR}`는 환경 변수를 읽고, `${headers.NAME}`은 호출자의 수신 요청에서 헤더를 전달해요(Docker Agent가 API 서버로 실행될 때 유용).
`allow_private_ips`	boolean	원격 MCP OAuth 헬퍼 요청이 비공개 IP 주소로 다이얼하는 것을 허용. 신뢰할 수 있는 내부 서버에만 사용하세요.

도구 자동 설치 (Auto-Installing Tools)

바이너리 명령이 필요한 MCP나 LSP 도구를 구성할 때, 명령이 시스템에 없으면 Docker Agent가 자동으로 다운로드·설치할 수 있어요. 이는 CLI 도구 패키지의 큐레이션된 인덱스인 aqua 레지스트리를 사용해요.

동작 방식 (How It Works)

command가 있는 도구셋이 로드되면 Docker Agent는 명령이 PATH에 있는지 확인해요.
없으면 Docker Agent 도구 디렉토리(~/.cagent/tools/bin/)를 확인해요.
그래도 없으면 aqua 레지스트리에서 명령을 찾아 자동 설치해요.

명시적 패키지 참조 (Explicit Package Reference)

version 속성으로 정확히 어떤 패키지를 설치할지 지정해요:

toolsets:
- type: mcp
  command: gopls
  version: "golang/[email protected]"
  args: [ "mcp" ]
- type: lsp
  command: rust-analyzer
  version: "rust-lang/rust-analyzer@2024-01-01"
  file_types: [ ".rs" ]

형식은 owner/repo 또는 owner/repo@version이에요. 버전을 생략하면 최신 릴리스를 사용해요.

자동 감지 (Automatic Detection)

version 속성이 없으면 Docker Agent는 aqua 레지스트리를 검색해 명령 이름에서 패키지를 자동 감지하려 해요:

toolsets:
- type: mcp
  command: gopls # auto-detected as golang/tools
  args: [ "mcp" ]

체크섬 검증 (Checksum Verification)

aqua 레지스트리가 체크섬 매니페스트를 포함하면 다운로드된 바이너리는 설치 전에 그에 대해 검증돼요. 검증 동작은 광고된 체크섬 유형에 따라 달라요:

강한 체크섬(sha256, sha512 등) — 바이너리 설치 전에 검증해요. 다운로드된 아카이브가 일치하지 않으면 설치가 중단되고 오류가 반환돼요(fail closed).
지원되지 않거나 약한 체크섬 유형(예: md5, sha1) — 경고와 함께 건너뛰고 검증 없이 설치를 진행해요.
매니페스트 없음 — 레지스트리 항목에 체크섬이 광고되지 않으면 바이너리는 검증 없이 설치돼요.

version_overrides 해석 (version_overrides Resolution)

자동 설치기는 aqua 레지스트리의 version_overrides 항목을 올바르게 해석해요. 많은 일반 도구(예: fzf)는 다운로드 URL과 체크섬을 포함한 패키지 구성을 레지스트리 항목의 최상위가 아닌 version_overrides 아래에 유지해요. 이런 도구들은 이전에 조용히 설치에 실패했지만 지금은 올바르게 처리돼요.

자동 설치 비활성화 (Disabling Auto-Install)

도구셋별 — version을 "false" 또는 "off"로 설정:

toolsets:
- type: mcp
  command: my-custom-server
  version: "false"

전역 — DOCKER_AGENT_AUTO_INSTALL 환경 변수 설정:

export DOCKER_AGENT_AUTO_INSTALL = false

환경 변수 (Environment Variables)

변수	기본값	설명
`DOCKER_AGENT_AUTO_INSTALL`	(활성화)	`false`로 설정하면 모든 자동 설치 비활성화
`DOCKER_AGENT_TOOLS_DIR`	`~/.cagent/tools/`	설치된 도구의 기본 디렉토리
`GITHUB_TOKEN`	—	API 속도 제한을 올릴 GitHub 토큰(선택)

설치된 바이너리는 ~/.cagent/tools/bin/에 놓이고 캐시되어 한 번만 다운로드돼요.

팁: 자동 설치는 Go 패키지(go install 경유)와 GitHub 릴리스 바이너리(아카이브 다운로드 경유) 둘 다 지원해요. aqua 레지스트리 메타데이터가 어떤 방법을 쓸지 결정해요.

도구셋 라이프사이클 (Toolset Lifecycle)

장수 도구셋 — 로컬 MCP 서버(stdio), 원격 MCP 서버(Streamable HTTP / SSE), LSP 서버 — 은 단일 감독자가 관리하며, 충돌·시간 초과·세션 드롭 시 자동 재연결할 수 있어요. 도구셋의 lifecycle 블록으로 도구셋별로 그 감독자를 조정할 수 있어요. 모든 type: mcp와 type: lsp 도구셋에 적용돼요.

가장 단순한 손잡이는 profile로, 사전 설정을 골라요:

Profile	자동 재시작	용도
`resilient`	예	기본값. 연결 끊김 시 지수 백오프; 도구셋을 사용할 수 없어도 에이전트는 계속 실행돼요. 기존 Docker Agent 동작과 일치해요.
`strict`	아니오	Fail-fast. 도구셋을 필수로 표시해요. 누락된 의존성이 하드 오류여야 하는 CI / 헤드리스 실행용.
`best-effort`	아니오	단일 시도, 재시도 없음. 깜빡임이 재시작 루프로 증폭되어서는 안 되는 실험적 MCP에 좋아요.

toolsets:
- type: mcp
  ref: docker:duckduckgo
  lifecycle:
    profile: resilient # default; shown here for clarity

- type: lsp
  command: gopls
  file_types: [ ".go" ]
  lifecycle:
    profile: strict

- type: mcp
  ref: docker:openbnb-airbnb
  lifecycle:
    profile: best-effort

기본값 조정 (Tuning the defaults)

lifecycle에 설정된 어떤 필드든 profile 사전 설정을 재정의하므로 섞어 쓸 수 있어요: profile을 고르고 신경 쓰는 손잡이만 재정의하세요.

toolsets:
- type: mcp
  command: [ "docker", "mcp", "gateway" ]
  lifecycle:
    profile: resilient
    max_restarts: 10 # keep trying longer than the default of 5
    backoff:
      initial: 500ms
      max: 1m
      multiplier: 2
      jitter: 0.2 # 20% random offset to avoid thundering-herd retries

속성	타입	설명
`profile`	string	`resilient`(기본값), `strict`, `best-effort` 중 하나. 다른 모든 필드의 기본값을 골라요.
`restart`	string	연결 끊김 후 감독자가 재연결해야 할 때: `never`, `on_failure`(기본값), `always`. 원격 MCP 도구셋(Streamable HTTP / SSE)에서는 idle-timeout 종료가 우아하게 재연결되도록 `on_failure`가 자동으로 `always`로 승격돼요 — `never`는 여전히 지켜져요.
`max_restarts`	int	도구셋이 Failed로 표시되기 전의 최대 연속 재시작 시도. `0`은 profile 기본값(5)을 사용하고 `-1`은 무제한.
`backoff.initial`	duration	시도 사이 첫 대기(Go duration: `500ms`, `1s`, …). 기본값: `1s`.
`backoff.max`	duration	시도 사이 대기의 상한. 기본값: `32s`.
`backoff.multiplier`	number	각 시도마다 적용되는 승수. 기본값: `2`.
`backoff.jitter`	number	계산된 지연의 (0..1) 일부를 균일 랜덤 오프셋으로 적용. `0`은 jitter 비활성화(기본값).
`required`	boolean	도구셋을 중요로 표시. 현재는 정보 제공용. 미래 eager-startup 단계는 필수 도구셋이 Ready에 도달할 수 없으면 에이전트 시작을 거부할 것. `strict` 아래에서 기본 `true`, 그 외 `false`.
`startup_timeout`	duration	초기 connect+initialize 기간의 상한. v1.94.0부터 적용: 만료 시 도구셋은 중지된 채 유지되고 런타임은 다음 턴에 재시도해요.
`call_timeout`	duration	개별 도구 호출 기간의 상한(재연결-재시도 1회 포함). 적용: 만료 시 호출이 취소되고 모델에 도구 오류로 표면화되며, 취소는 서버에 전파돼요. `0`/미설정은 시간 초과 없음 — opt-in 전용, profile 기본값 없음.

참고 — required는 아직 적용되지 않아요: 스키마는 이 필드를 검증하고 감독자는 저장하지만 아직 그에 따라 동작하는 코드 경로는 없어요. 계획된 eager-startup 단계가 도래해도 오늘 작성된 구성 파일이 계속 동작하도록 지금 문서화하는 거예요. strict profile을 고르는 것은 전방 호환돼요 — required=true를 자동으로 적용하기 시작할 거예요.

런타임에 도구셋 검사·재시작 (Inspecting and restarting toolsets at runtime)

TUI는 감독자를 두 개의 슬래시 명령으로 노출해요:

/tools — 통합 도구 대화상자. 상단 섹션은 현재 에이전트의 모든 도구셋을 라이프사이클 상태(Stopped, Starting, Ready, Degraded, Restarting, Failed), 재시작 횟수, 마지막 오류와 함께 나열해요. 하단 섹션은 에이전트가 호출할 수 있는 모든 도구를 카테고리별로 그룹화해 나열해요. "에이전트가 무엇을 할 수 있나?"와 "무언가 저하됐나?"를 한 명령으로 답할 수 있어요.
/toolset-restart <name> — 감독자가 명명된 도구셋을 재연결하게 강제해요. OAuth 완료 후, 원격 MCP 서버가 재배포됐을 때, gopls 같은 LSP가 막혔을 때 유용해요.

슬래시 명령의 전체 목록은 TUI 참조를 보세요.

전체 lifecycle 구성 예제는 examples/lifecycle.yaml을 참조하세요.

TOON 인코딩 도구 출력 (TOON-Encoded Tool Outputs)

많은 MCP 서버는 컨텍스트 예산을 많이 소비하는 장황한 JSON 응답을 반환해요. 도구셋의 toon 필드는 일치하는 도구의 JSON 출력을 모델에 보여주기 전에 TOON — 컴팩트하고 모델 친화적인 key/value 형식 — 으로 투명하게 재인코딩해요.

toolsets:
- type: mcp
  ref: docker:github-official
  toon: ".*" # toonify every tool from this MCP server
- type: mcp
  command: my-server
  toon: "list_.*,get_.*" # only toonify list_/get_ tools

속성	타입	설명
`toon`	string	JSON 출력을 TOON으로 재인코딩해야 하는 도구 이름과 일치하는 정규식의 쉼표 구분 목록. 비-JSON 출력과 비일치 도구는 그대로 통과돼요.

도구의 출력이 유효한 JSON이 아니면 변경 없이 반환돼요 — TOON 인코딩은 best-effort이고 평문 텍스트를 내는 도구를 절대 깨지 않아요.

참고 — TOON을 언제 사용할까: TOON은 보통 레코드 배열을 반환하는 MCP 도구(이슈 목록, 검색 결과, 파일 목록, …)에 대해 JSON보다 30-60% 더 작은 페이로드를 만들어요. 스키마가 규칙적일 때 가장 잘 동작해요. 깊게 중첩되거나 이질적인 모양의 일회성 응답은 이점이 적을 수 있어요.

도구셋별 모델 라우팅 (Per-Toolset Model Routing)

도구셋의 model 필드는 그 도구셋의 도구가 반환된 후 다음 턴에 호출되는 LLM을 재정의해요 — 단순한 도구 결과(파일 읽기, 지식 베이스 조회, 셸 stdout)를 더 싸고 빠른 모델로 처리하면서 에이전트의 기본 모델은 추론에 유지하게 해줘요.

models:
  primary:
    provider: anthropic
    model: claude-sonnet-4-5
  fast:
    provider: anthropic
    model: claude-haiku-4-5

agents:
  root:
    model: primary
    toolsets:
    - type: filesystem
      model: fast # process file reads with the fast model
    - type: shell
      model: fast # ditto for shell stdout
    - type: mcp
      ref: docker:github-official
      model: openai/gpt-4o-mini # inline provider/model also works

속성	타입	설명
`model`	string	이 도구셋의 도구 결과를 처리하는 LLM 턴에 사용하는 모델. `models:` 섹션의 이름 또는 인라인 `provider/model`(예: `openai/gpt-4o-mini`). 재정의는 one-shot이에요: 이후 턴은 에이전트 기본 모델로 돌아가요.

한 턴의 여러 도구 호출이 서로 다른 모델 재정의를 가진 도구셋에서 오면, 런타임은 설정된 재정의가 있는 첫 번째 도구 호출의 것을 골라요. 전체 구성은 examples/per_tool_model_routing.yaml을 참조하세요.

도구 필터링 (Tool Filtering)

도구셋은 많은 도구를 노출할 수 있어요. tools 속성으로 에이전트가 필요로 하는 것만 화이트리스트할 수 있어요. 이것은 MCP뿐 아니라 모든 도구셋 유형에서 동작해요:

toolsets:
- type: mcp
  ref: docker:github-official
  tools: [ "list_issues", "create_issue", "get_pull_request" ]
- type: filesystem
  tools: [ "read_file", "search_files_content" ]
- type: shell
  tools: [ "shell" ]

팁: 도구 필터링은 에이전트 성능을 높여요 — 도구가 적을수록 모델이 어떤 도구를 쓸지 혼동이 적어요.

도구 지시 (Tool Instructions)

도구셋이 로드될 때 주입되는 컨텍스트별 지시를 추가해요:

toolsets:
- type: mcp
  ref: docker:github-official
  instruction: |
    Use these tools to manage GitHub issues.
    Always check for existing issues before creating new ones.
    Label new issues with 'triage' by default.

기본적으로 instruction: 필드는 도구셋의 내장 지시(있으면)를 대체해요. 내장 안내를 유지하고 그 위에 자신의 규칙을 추가하려면 지시 텍스트 어디든 {ORIGINAL_INSTRUCTIONS} 플레이스홀더를 포함하세요. 런타임에 도구셋의 기본 지시로 확장돼요:

toolsets:
# Enrich: keep built-in instructions, then add your own rules
- type: filesystem
  instruction: |
    {ORIGINAL_INSTRUCTIONS}

    ## Project-specific rules
    - Never modify files outside the `src/` directory.
    - Always create a backup before overwriting a file.

# Enrich: prepend your rules before the built-in instructions
- type: shell
  instruction: |
    Important: only run commands inside the project root.
    {ORIGINAL_INSTRUCTIONS}

# Replace: omit the placeholder to discard built-in instructions entirely
- type: mcp
  ref: docker:github-official
  instruction: |
    Only read GitHub issues. Never create, edit, or close anything.

세 가지 패턴을 한눈에:

패턴	설명
`{ORIGINAL_INSTRUCTIONS}` 다음에 내 텍스트	내 규칙을 기본값 뒤에 추가
내 텍스트 다음에 `{ORIGINAL_INSTRUCTIONS}`	내 규칙을 기본값 앞에 추가
플레이스홀더 없음	기본값을 완전히 대체

전체 예제는 examples/toolset_instructions.yaml을 참조하세요.

지연된 도구 로딩 (Deferred Tool Loading)

에이전트 시작을 빠르게 하기 위해 도구를 온디맨드로 로드해요. 도구셋이 defer되면 그 도구는 지연 등록돼요 — 에이전트가 그 도구 중 하나를 처음 호출할 때까지 도구 서버 프로세스가 시작되지 않아요. 수백 개 도구가 있는 MCP 서버처럼 시작 시간이 중요한 큰 도구셋에 유용해요.

toolsets:
- type: mcp
  ref: docker:github-official
  defer: true
- type: mcp
  ref: docker:slack
  defer: true
- type: filesystem

또는 도구셋 내 특정 도구만 defer:

toolsets:
- type: mcp
  ref: docker:github-official
  defer:
  - "list_issues"
  - "search_repos"

defer가 도구 이름 목록이면 그 특정 도구만 defer돼요. 도구셋의 다른 모든 도구는 즉시(전역적으로) 로드돼요. defer: true는 전체 도구셋을 defer해요.

search_tool로 도구 발견 (Tool Discovery with search_tool)

전체 도구셋이 defer되면(defer: true), defer된 도구셋은 에이전트에 두 개의 내장 도구를 노출해요:

search_tool — 키워드로 사용 가능한 지연 도구를 발견. 검색은 도구 이름과 설명 둘 다에 대해 퍼지 매칭을 사용해요. 쿼리의 모든 문자는 순서대로 대상 문자열에 나타나야 해요(반드시 인접할 필요는 없음). "crfil" 같은 쿼리는 create_file과 일치해요. 일치하는 도구 이름과 설명 목록을 반환해요.
add_tool — 발견된 도구를 이름으로 활성화해 사용 가능하게 해요.

이 도구들은 에이전트가 모든 도구를 미리 활성화하지 않고도 큰 도구셋을 온디맨드로 탐색하게 해줘요.

전체 예제는 examples/deferred.yaml을 참조하세요.

결합 예제 (Combined Example)

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Full-featured developer assistant
    instruction: You are an expert developer.
    toolsets:
    # Built-in tools
    - type: filesystem
    - type: shell
    - type: think
    - type: todo
    - type: memory
      path: ./dev.db
    - type: user_prompt

    # LSP for code intelligence
    - type: lsp
      command: gopls
      file_types: [ ".go" ]

    # Custom scripts
    - type: script
      shell:
        run_tests:
          description: Run the test suite
          cmd: task test
        lint:
          description: Run the linter
          cmd: task lint

    # Custom API tool
    - type: api
      api_config:
        name: get_status
        method: GET
        endpoint: "https://api.example.com/status"
        instruction: Check service health

    # Docker MCP tools
    - type: mcp
      ref: docker:github-official
      tools: [ "list_issues", "create_issue" ]
    - type: mcp
      ref: docker:duckduckgo

    # Remote MCP
    - type: mcp
      remote:
        url: "https://internal-api.example.com/mcp"
        transport_type: "streamable"
        headers:
          Authorization: "Bearer ${env.INTERNAL_TOKEN}"

경고 — 도구셋 순서가 중요해요: 여러 도구셋이 같은 이름의 도구를 제공하면 첫 번째가 이겨요. 도구셋을 의도적으로 순서화하세요.