Tool 런타임

turn 중에 worker는 model이 호출할 수 있는 tool 집합을 조립하고, 각 tool의 schema를 model이 보는 JSON Schema로 변환하며, model이 만든 각 function call을 해당 tool의 execute 함수로 dispatch합니다. 이 페이지는 그 런타임을 설명합니다. WorkerAgentTool contract, turn별 tool 집합이 조립되는 방식, schema가 수집되는 방식, loop가 호출을 dispatch하는 방식이 그것입니다. 이 문서는 Agent loop와 Agent Computer Worker를 기반으로 합니다.

핵심 속성을 먼저 말하면, tool은 turn마다 조립됩니다. 각 turn은 computer, web, schedule, background job 및 기타 현재 소스에서 최종 tool 집합을 구성합니다. Agent가 소유한 전역 tool 집합은 없습니다. MCP-backed Skill은 computer command tool과 mcporter를 사용합니다.

WorkerAgentTool 계약

모든 Worker tool은 defineWorkerTool로 WorkerAgentTool을 구성합니다. 런타임이 신경 쓰는 필드는 다음과 같습니다.

필드	타입	역할
`name`	string	model이 보고 호출하는 tool 이름
`description`	string	tool이 하는 일 — model은 이것을 읽고 호출 여부를 결정합니다
`schema`	Zod schema	`execute`가 실행되기 전에 검증되는 입력 매개변수
`jsonSchema`	JSON Schema(선택)	생성된 Zod schema 대신 사용되는 라이브 외부 schema
`strict`	boolean(선택)	Provider가 해당 function schema를 strict mode로 적용할지 여부
`namespace` / `namespaceDescription`	string(선택)	관련 외부 tool을 하나의 provider namespace 아래로 묶습니다
`deferLoading`	boolean(선택)	하위 schema를 선택될 때까지 Tool Search 뒤에 유지합니다
`executionMode`	`'parallel' \| 'sequential'`	같은 응답에서 다른 tool과 함께 실행될 수 있는지 여부
`isReadOnly` / `isDestructive`	boolean	활동 보고와 안전 검사를 위한 메타데이터
`describeActivity`	function	검증된 매개변수에서 짧은 사람이 읽을 수 있는 라벨을 만듭니다(진행 상황용)
`describeCompletedActivity`	function(선택)	tool이 끝나면 라벨을 결과 요약으로 교체합니다
`execute`	function	tool을 실행합니다. 콘텐츠, 세부 정보, 선택적 presentation 이벤트를 반환하며 turn을 종료할 수 있습니다

execute 함수가 tool의 실제 작업입니다. 검증된 매개변수(schema가 이미 파싱하고 검사함)와 abort signal을 받아 AgentToolResult를 반환합니다. 이는 model이 보는 콘텐츠, 로깅용 구조화된 세부 정보, 선택적 응답 presentation 이벤트, 그리고 actor event를 완료하거나 turn을 종료하는 선택적 플래그로 구성됩니다.

turn마다 tool 집합이 조립되는 방식

text_turn.ts는 각 turn 시작 시 category creator에서 tool을 조합하여 tool 집합을 구성합니다.

tools = [
  createTodoTool(...),
  ...createComputerTools({...}),
  ...webTools,
  ...scheduleTools,
  ...backgroundAgentJobTools,
  createWorkflowTool(...),
  createShowWorkflowTool(...),
  createListWorkflowsTool(...),
  createCancelWorkflowTool(...),
  ...
]

각 category creator는 turn의 context(worker 환경, agent의 홈, RPC client, abort signal)로 구성된 하나 이상의 WorkerAgentTool 객체를 반환하는 함수입니다. 조립은 명시적이고 순서가 있으며, reflection도 auto-discovery도 decorator 스캔도 없습니다. tool이 배열에 있으면 사용 가능하고, 없으면 사용할 수 없습니다.

turn별 조립 덕분에 tool 집합이 동적입니다.

Skill 지식은 Agent의 현재 활성화된 Skill에서 투영됩니다. MCP-backed Skill은 도메인 tool을 선택하고 기존 computer command tool을 사용하여 mcporter를 호출합니다.
Web tools는 worker의 web_search/web_fetch provider 가용성에서 만들어집니다. profile이 바인딩되지 않으면 tool이 없습니다.
Background job tools는 turn의 context에서 만들어지며, turn이 job 생성을 지원할 때만 사용할 수 있습니다.
Workflow tools는 일반 text turn에 workflow, show_workflow, list_workflows, cancel_workflow를 추가합니다. Workflow task turn은 이 조립 경로를 사용하지 않습니다.

최종 tool 집합은 여전히 turn별 결과이지, Agent 기능 데이터베이스나 준비된 연결 풀이 아닙니다.

Schema 수집

model은 Zod가 아닌 JSON Schema가 필요합니다. tool-schema.ts는 각 tool의 Zod schema를 변환합니다.

export function zodToJSONSchema(schema: z.ZodType): JSONObject {
  const jsonSchema = z.toJSONSchema(schema) as JSONObject
  if (jsonSchema.type !== 'object') {
    throw new Error('function tool parameters must use a root object schema')
  }
  return jsonSchema
}

수집된 schema(tool당 하나, 여기에 tool 이름과 설명 포함)는 Responses 요청으로 model에 전송됩니다. 구체적인 외부 adapter가 jsonSchema를 제공하면 Ankole은 Zod에서 생성하는 대신 해당 schema를 경계에서 변경 없이 전송하며, minimum과 maximum 같은 제약 조건도 그대로 유지됩니다. 이후의 projection은 별도의 native runtime이 담당합니다. 지연된(deferred) children은 선택될 때까지 Tool Search 뒤에 남습니다.

model이 function call을 반환하면 해당 인수는 JSON 문자열로 도착합니다. validateToolArguments는 tool의 Zod schema를 기준으로 문자열을 파싱하며, 잘못된 형태의 인수(잘린 JSON, 코드 fence 안의 JSON, 균형이 맞지 않는 객체)를 위한 제한된 복구 사다리가 있습니다. tool의 execute는 원시 model 출력을 절대 받지 않으며, schema로 검증된 매개변수를 받습니다.

Workflow task의 동적 결과 schema

Workflow task는 일반 text turn과 다른 고정 tool 목록을 사용합니다. Web tools, Brain이 활성화된 경우의 읽기 전용 recall/get_page, 그리고 task별 submit_result만 제공합니다. 따라서 task는 다른 Workflow나 Background Agent Job을 만들 수 없습니다.

submit_result의 jsonSchema는 Workflow script가 해당 task에 저장한 result schema에서 만듭니다. Worker는 이 schema를 strict: true로 Provider에 보내고, 제어 플레인은 제출된 값을 다시 검증한 뒤에만 PostgreSQL에 저장합니다. schema 거부는 task turn을 종료하지 않으므로 서브에이전트가 값을 고쳐 다시 제출할 수 있습니다. 지원되는 닫힌 schema 형태는 Workflows에서 설명합니다.

loop가 호출을 dispatch하는 방식

model의 응답에 function-call 항목이 포함되면 agent loop은 다음을 수행합니다.

tool map 구성 — agentToolMap(tools)가 배열을 tool 이름을 키로 하는 Map<string, AgentTool>로 변환합니다.
인수 검증 — 각 호출의 인수 문자열을 tool의 schema에 대해 파싱하고 검증하며, 필요하면 복구합니다.
실행 — tool의 execute 함수가 검증된 매개변수와 abort signal로 실행됩니다. executionMode: 'parallel'인 tool은 동시에 실행될 수 있고, sequential tool은 순서대로 실행됩니다.
결과 기록 — AgentToolResult가 function-call-output 메시지로 AIGateway에 전송되며, model은 다음 반복에서 이를 봅니다.

loop가 반복을 소유합니다. model을 호출하고, tool을 실행하고, 결과를 기록하며 model이 더 이상 function call을 반환하지 않을 때까지 반복합니다. tool은 언제 실행할지 결정하지 않으며, loop가 model이 요청한 내용에 따라 결정합니다.

이 가이드가 다루지 않는 것

이 가이드는 tool 작성 튜토리얼이 아닙니다. 새 tool은 defineWorkerTool로 WorkerAgentTool을 구성하며, 기존 category(tools/computer/, tools/web/)가 참조 예시입니다. model 행동 가이드도 아닙니다. model이 어떤 tool을 호출하는지는 런타임이 아니라 persona의 영역입니다. 그리고 agent loop 페이지를 대체하지도 않습니다. dispatch 경로는 loop의 일부이며, loop 페이지가 그 맥락입니다.

다음 단계

tool 호출을 dispatch하는 loop는 Agent loop를 참조하세요.
tool을 실행하는 Agent Computer Worker는 Agent Computer Worker를 참조하세요.
Skill 뒤의 MCP 실행 dependency는 MCP server 참조를 참조하세요.
MCP dependency를 지니는 skill은 Skill 작성을 참조하세요.
동적 task result schema와 서브에이전트 도구 경계는 Workflows를 참조하세요.