# Fluxo entre agentes

Transfira uma decisão, uma correção de implementação e um contexto limitado entre agentes identificados usando os contratos existentes do SDK e do MCP.

- Canonical: https://docs.xmemo.dev/pt-br/docs/operations/cross-agent-workflow
- Locale: pt-BR
- Content-Locale: pt-BR
- Canonical-Content-Digest: 601017a1cc889872d5526e3d5cb8ee1ac73c89512eb78d284d88811d2349b611
- Edition-Digest: 566d61c1b270fec91bf83d574fd3be20c8f4e562d4cf81218d8e34564f7fef4d
- Source-Revision: sha256:9e1f7f01cc46df74b247f9cecea3b932f1b046cd1751624acdfd046a7b7fedd2

## 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.

```text
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.

```ts
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.

```ts
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.

```text
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.

```json
{
  "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.

```text
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.
```