Fluxo entre agentes

Um handoff, duas superfícies existentes

Um handoff entre agentes não adiciona uma nova API. O agente que escreve pode usar os auxiliares de fluxo do SDK TypeScript taskStart, recordDecision, recordBugFix e taskEnd; o agente que recebe pode usar a ferramenta MCP recall_context ou o método do SDK recallContext. Os nomes de agente abaixo são valores de atribuição transportados por solicitações existentes, enquanto a chave da API ou a concessão OAuth e os escopos memory:read / memory:write continuam autorizando o acesso.

• Claude grava a decisão por meio do adaptador conectado ou do cliente SDK.
• Codex recupera o contexto limitado, registra a correção e encerra a tarefa.
• Claude chama recall_context novamente e recebe a decisão e a correção compartilhadas quando o proprietário autenticado e o escopo solicitado permitem.

Linha do tempo do handoff

A ordem do ciclo de vida é taskStart → recall_context → recordDecision → recordBugFix → taskEnd → recall_context de outro agente. taskStart e taskEnd usam por padrão um tipo de memória working com status started e completed; recordDecision e recordBugFix usam por padrão memória semantic. Todo auxiliar de captura do SDK resolve para CaptureResult, portanto o chamador deve inspecionar shouldCapture antes de presumir que uma memória foi gravada.

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 })

Grave a decisão com o SDK

Os métodos do SDK usam os campos existentes de AgentWorkflowOptions. Mantenha source, identidade do agente, sessionId, taskId e scope estáveis durante o handoff; não coloque a chave da API nas opções nem no conteúdo gravado.

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);
}

Recupere, corrija e encerre a tarefa

MCP recall_context é o pacote limitado de contexto com várias memórias e exige memory:read. O método recallContext do SDK chama POST /v1/recall/context e retorna o objeto JSON estruturado. O Codex pode usar qualquer uma das superfícies para a leitura e, depois, usar os auxiliares existentes do SDK para a correção e o encerramento da tarefa.

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);

A leitura MCP equivalente

Na superfície MCP pública, use a ferramenta existente com nome em snake_case e seus argumentos públicos também em snake_case: query, max_items e max_tokens. O perfil conectado fornece o proprietário autenticado e a identidade do agente; o servidor anota os itens retornados com o objeto de limite do agente. max_items e max_tokens limitam todo o pacote de contexto. A ferramenta retorna uma resposta pública em texto que começa com ### XMemo Context.

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

Leia os campos de limite, não apenas o conteúdo

O resultado de recall é anotado com o objeto de limite do agente existente. Se o Codex lê uma memória gravada com agent_id=claude, a relação é other_agent e a propriedade é other_agent; se o agent_id lógico coincide, mas o hash da instalação é diferente, a relação é same_agent_other_instance. Quando agent_id e agent_instance_id_hash coincidem, é self. boundary_authority permanece attribution_only, e current_agent_trust é token_bound somente quando a origem da identidade é vinculada ao token; caso contrário, é 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"
}

Retome com o mesmo escopo e uma consulta limitada

O recall de acompanhamento do Claude usa a mesma conta autenticada e o mesmo escopo, mas seus próprios valores de agent_id e agent_instance_id. A memória continua compartilhada somente quando a credencial do chamador, o escopo memory:read, o limite do proprietário e os filtros de recuperação solicitados permitem; um rótulo de limite do agente é evidência de atribuição, não um desvio de autorização.

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.