시작하기가이드에이전트 간 워크플로

Guide

에이전트 간 워크플로

기존 SDK 및 MCP contract를 사용해 이름이 지정된 agent 사이에서 결정, 구현 수정, 제한된 context를 전달합니다.

하나의 handoff, 두 개의 기존 surface

에이전트 간 handoff는 새 API를 추가하지 않습니다. 작성 agent는 TypeScript SDK workflow helper인 taskStart, recordDecision, recordBugFix, taskEnd를 사용할 수 있고, 받는 agent는 MCP tool recall_context 또는 SDK method recallContext를 사용할 수 있습니다. 아래 agent 이름은 기존 request가 전달하는 attribution 값이며, API key 또는 OAuth grant와 memory:read / memory:write scope가 여전히 access를 승인합니다.

  • Claude는 연결된 adapter 또는 SDK client를 통해 결정을 기록합니다.
  • Codex는 제한된 context를 recall하고, 수정 사항을 기록한 뒤 task를 닫습니다.
  • 인증된 owner와 요청된 scope가 허용하면 Claude가 recall_context를 다시 호출해 공유된 결정과 수정 사항을 받습니다.

Handoff timeline

lifecycle 순서는 taskStart → recall_context → recordDecision → recordBugFix → taskEnd → 다른 agent의 recall_context입니다. taskStart와 taskEnd는 기본적으로 started 및 completed status의 working memory type을 사용하고, recordDecision과 recordBugFix는 기본적으로 semantic memory를 사용합니다. 모든 SDK capture helper는 CaptureResult로 resolve되므로 caller는 memory가 기록되었다고 가정하기 전에 shouldCapture를 확인해야 합니다.

1. Claude: client.taskStart(...)
2. Codex: recall_context({ query, max_items, max_tokens })
3. Claude: client.recordDecision(...)
4. Codex: client.recordBugFix(...)
5. Codex: client.taskEnd(...)
6. Claude: recall_context({ query, max_items, max_tokens })

SDK로 decision 기록하기

SDK method는 기존 AgentWorkflowOptions field를 사용합니다. handoff 동안 source, agent identity, sessionId, taskId, scope를 안정적으로 유지하고, API key를 option이나 기록되는 content에 넣지 않습니다.

const scope = 'memory-os';
const sessionId = 'handoff-session-1';
const taskId = 'handoff-1';

await claude.taskStart('Review the deployment adapter', {
  source: 'claude', sessionId, taskId, scope,
});
const decision = await claude.recordDecision(
  'Use the hosted network MCP transport for remote agents.',
  { source: 'claude', sessionId, taskId, scope },
);
if (!decision.shouldCapture) {
  throw new Error('Decision was not captured: ' + decision.reason);
}

Recall하고 수정한 뒤 task 닫기

MCP recall_context는 memory:read가 필요한 제한된 multi-memory context pack입니다. SDK의 recallContext method는 POST /v1/recall/context를 호출하고 구조화된 JSON object를 반환합니다. Codex는 read에 어느 surface든 사용할 수 있으며, 이후 기존 SDK helper로 bug fix와 task close를 수행합니다.

const context = await codex.recallContext(
  'deployment adapter decision and current bug',
  { scope, maxItems: 6, maxTokens: 1200, preferWorking: true },
);

await codex.recordBugFix(
  'Fixed streamable-http token identity fallback.',
  { source: 'codex', sessionId, taskId, scope },
);
await codex.taskEnd(
  'Deployment adapter fix completed for handoff.',
  { source: 'codex', sessionId, taskId, scope },
);
console.log(context.version, context.items);

동등한 MCP read

공개 MCP surface에서는 기존 underscore 이름의 tool과 public snake_case argument인 query, max_items, max_tokens를 사용합니다. 연결된 profile이 인증된 owner와 agent identity를 제공하고, server는 반환 item에 agent boundary object를 주석으로 붙입니다. max_items와 max_tokens는 전체 context pack을 제한합니다. tool은 ### XMemo Context로 시작하는 public text response를 반환합니다.

recall_context({
  query: "deployment adapter decision and current bug",
  max_items: 6,
  max_tokens: 1200
})

content body만이 아니라 boundary field 읽기

Recall result에는 기존 agent boundary object가 주석으로 붙습니다. Codex가 agent_id=claude로 기록된 memory를 읽으면 relation과 ownership은 other_agent이고, logical agent_id가 같지만 installation hash가 다르면 relation은 same_agent_other_instance입니다. agent_id와 agent_instance_id_hash가 모두 같으면 self입니다. boundary_authority는 attribution_only로 유지되고, identity source가 token-bound일 때만 current_agent_trust가 token_bound이며 그렇지 않으면 client_asserted입니다.

{
  "relation": "other_agent",
  "ownership": "other_agent",
  "current_agent_id": "codex",
  "current_agent_trust": "client_asserted",
  "boundary_authority": "attribution_only",
  "memory_agent_id": "claude",
  "explanation": "memory agent_id differs from this caller"
}

같은 scope와 제한된 query로 재개하기

Claude의 후속 recall은 같은 인증 account와 scope를 사용하지만 자체 agent_id 및 agent_instance_id 값을 사용합니다. caller의 credential, memory:read scope, owner boundary와 요청된 retrieval filter가 허용하는 경우에만 memory가 공유됩니다. agent boundary label은 attribution 증거이지 authorization 우회 수단이 아닙니다.

recall_context({
  query: "deployment adapter decision, Codex fix, and handoff status",
  max_items: 6,
  max_tokens: 1200
})
# Inspect the returned context and boundary summary before continuing.

출처: TypeScript SDK workflow helpers