도구와 툴셋

도구 시스템은 세 가지 질문에 답합니다. 도구는 어디 정의되는가 (레지스트리), 매 호출에 어떤 도구를 싣는가 (deferred loading), 서브에이전트에게 어떤 도구를 주는가 (툴킷)입니다.

레지스트리

core/tools/registry.py의 ToolRegistry가 네이티브 도구를 관리합니다. 정의의 SoT는 core/tools/definitions.json 하나입니다. 이름, 설명, 입력 스키마가 모두 여기 모이고, 핸들러는 카테고리 모듈에서 이름으로 연결됩니다. MCP 클라이언트(core/mcp/)가 발견한 외부 도구는 호출 시점에 네이티브 도구와 병합됩니다. MCP 서버 참고.

Deferred loading

도구 검색은 레지스트리를 대체하지 않습니다. 실행 가능한 도구를 권한 정책으로 걸러 ToolPlan에 고정한 뒤, 어댑터가 해당 요청의 지연 로딩 대상과 모델·API 지원 조건을 확인합니다. 지원 경로에서는 전체 정의를 서버에 보내되 모델의 초기 컨텍스트에는 일부만 싣습니다. 정의를 네트워크 요청에서 생략한다는 뜻은 아닙니다.

즉시 로드 core set은 TOOL_SEARCH_ALWAYS_LOADED입니다. 기억, 노트, 파일 읽기, 웹 탐색, 상태 확인처럼 검색 왕복을 치르면 손해인 고빈도 도구가 여기에 남습니다. 이 정책은 도구 계획을 만들 때 적용하며, 어댑터가 별도 목록으로 다시 선택하지 않습니다.

따라서 도구가 deferred loading 뒤로 밀렸다는 말은 모든 도구가 보이지 않는다는 뜻이 아닙니다. read_document, grep_files처럼 핵심 읽기 도구는 항상 적재됩니다. 이런 도구가 반복 호출된다면 모델이 더 많은 근거 파일을 읽겠다고 판단했을 가능성이 큽니다.

프로바이더별 경계

2026-09-20 공식 계약 점검 기준입니다. 아래 Anthropic 경계·이력 보강은 Unreleased 변경이며 실제 계정 호출은 별도 검증입니다.

Anthropic의 server_tool_use와 검색 결과는 assistant 이력으로 보존하며 로컬 실행기에 넘기지 않습니다. 실제로 발견된tool_use에만 실행 결과를 반환합니다. 스킬은 별도로 짧은 metadata를 먼저 보여주고 use_skill로 지침 본문을 읽습니다. 스킬 카탈로그는 함수 스키마 검색과 다른 책임입니다.

근거: OpenAI tool search, Anthropic tool search, OpenRouter tool search, Claude Code endpoint 정책.

응답과 재전송 계약

Unreleased: provider의 refusal은 번역 과정에서도 보존하여 도구 실행 전에 종료합니다. 분류된 거절 사유만 남기며 임의의 provider 설명을 진단 이벤트로 복사하지 않습니다. 출력 한도·미완료 등의 종료 사유도 보존하지만, 이는 해당 사유별 새 자동 재개 정책을 구현했다는 뜻은 아닙니다.

GLM과 OpenRouter의 Chat Completions reasoning 필드는 기존 assistant 이력과 비공개 세션 저장에 보존합니다. 다음 요청은 provider·어댑터·모델이 모두 일치할 때만 원본 필드를 재전송합니다. 다른 provider의 입력이나 공개 trajectory로 옮기지 않습니다. OpenAI 출력 스키마는 객체 루트와 지원 구문을 확인한 뒤 strict 여부를 정하며, 잘못된 루트는 네트워크 호출 전에 거절합니다. 모든 provider가 같은 strict 보장을 제공한다는 뜻은 아닙니다.

툴킷: 서브에이전트 도구 번들

서브에이전트는 선언된 도구 번들만 받습니다. 매니페스트는 core/tools/toolkits.toml, 해석기는 core/tools/toolkit_registry.py입니다.

1. 에이전트 frontmatter의 toolkit: 이름이 있으면 그 툴킷을 사용합니다. includes:는 재귀적으로 펼쳐집니다.
2. 레거시 tools: 목록이 있으면 그대로 사용합니다.
3. 둘 다 없거나 이름이 틀리면 읽기 전용 _default(read_document, grep_files)로 폴백합니다.

조합용 leaf는 common_read와 common_write, 선언용 킷은 web_research, data_analysis, general_purpose 등입니다. 존재하지 않는 도구 이름은 스폰 시점에 경고를 내고 그 도구 없이 실행됩니다 (core/agent/worker.py).

대형 결과: 오프로드와 recall

모델에 전달할 도구 결과가 기본 15,000 토큰 임계값을 넘으면 core/orchestration/tool_offload.py의 ToolResultOffloadStore가 본문을 세션별 디렉터리 (.geode/tool-offload/ 아래)에 내려쓰고, 컨텍스트에는 요약과 ref_id만 남깁니다. 모델이 원본이 필요하면 recall_tool_result(ref_id)로 다시 가져옵니다. 오프로드마다 TOOL_RESULT_OFFLOADED 훅이 발화합니다.

MCP 결과는 evidence용 원본과 model-facing 표현을 분리합니다. timeline과 tool log에는 전체 CallToolResult를 남기고, 모델에는 structuredContent를 우선한 단일 표현만 보냅니다. 호환성용 content 복제본을 다시 직렬화하지 않으며, 오프로드 뒤 25,000-token hard guard가 최종 상한을 보장합니다.

접근 제어

어떤 도구를 누가 쓸 수 있는지는 core/tools/policy.py의 PolicyChain이 6단계로 해석합니다. Profile, Organization, Mode, Agent 레벨, Node-scope allowlist, 서브에이전트 자동 승인 위임 순서입니다. 권한 등급은 STANDARD(서브에이전트 자동 승인 가능), WRITE(승인 필요), DANGEROUS(항상 HITL. run_bash, computer)입니다. delegate_task는 별도 위임 경로로 실행되며, 사람이 없는 headless 세션에서는 denylist가 먼저 막습니다.

switch_model 승인 요청에는 JSON으로 인코딩한 role과 model_hint가 표시됩니다. 역할을 생략하면 실행 핸들러와 같은 primary가 표시되므로, root 모델 변경과 judgment 전환을 승인 전에 구분할 수 있습니다. 이 상세 정보는 기존 승인 정책을 대체하지 않으며, 기본 HITL 2에서는 최초 judgment 전환도 승인 대상입니다.

실패 모드

다음

• MCP 서버. 외부 도구가 합류하는 클라이언트 측.
• 서브에이전트 오케스트레이션. 툴킷이 적용되는 실행 주체.
• 커스텀 도구 만들기. definitions.json에 도구를 추가하는 절차.