@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/pt-BR/a2a-protocol.md

@@ -0,0 +1,392 @@
+---
+title: "Protocolo A2A"
+description: "Comunicação entre agentes via JSON-RPC: descoberta, mensagens, streaming e gerenciamento de tarefas."
+---
+
+# Protocolo A2A
+
+Comunicação entre agentes por HTTP. Os agentes se descobrem, enviam mensagens e recebem resultados estruturados.
+
+## Visão geral {#overview}
+
+A2A (agente para agente) é um protocolo JSON-RPC para comunicação entre agentes. Um agente de e-mail pode solicitar a um agente analítico que execute uma consulta. Um agente de calendário pode pesquisar problemas em um agente de gerenciamento de projetos. Cada agente expõe suas capacidades por meio de um cartão de agente e aceita trabalho por meio de um endpoint JSON-RPC padrão.
+
+A2A é o substrato para delegação entre aplicativos nesta estrutura, principalmente para [Dispatch](/docs/dispatch), que roteia uma única mensagem de entrada (Slack, e-mail etc.) para qualquer aplicativo no espaço de trabalho que seja mais adequado para lidar com ela.
+
+Conceitos principais:
+
+- **Cartão do agente** — metadados públicos em `/.well-known/agent-card.json` que descrevem skills e recursos
+- **JSON-RPC** — aplicativos nativos do agente usam `POST /_agent-native/a2a`; peers externos/legados podem usar `POST /a2a`
+- **Tarefas** — cada mensagem cria uma tarefa com um ciclo de vida (enviada, em funcionamento, concluída, com falha, cancelada)
+- **Autenticação do portador JWT** — a produção A2A requer `A2A_SECRET` ou um `apiKeyEnv` legado explícito
+
+```an-diagram title="One agent hands work to another" summary="A mail agent discovers the analytics agent's card, sends a JSON-RPC message, and gets a completed task back."
+{
+  "html": "<div class=\"diagram-handoff\"><div class=\"diagram-card\"><strong>Mail agent</strong><small class=\"diagram-muted\">needs analytics</small></div><div class=\"diagram-col\"><div class=\"diagram-pill\">GET /.well-known/agent-card.json</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">POST /_agent-native/a2a<br><small class=\"diagram-muted\">message/send</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&larr;</div><div class=\"diagram-pill ok\">task · completed</div></div><div class=\"diagram-card\" data-rough><strong>Analytics agent</strong><small class=\"diagram-muted\">runs run-query, returns result</small></div></div>",
+  "css": ".diagram-handoff{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-handoff .diagram-col{display:flex;flex-direction:column;align-items:center;gap:6px}.diagram-handoff .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+## Configuração do servidor {#server-setup}
+
+A maioria dos modelos obtém A2A por meio do plugin de chat do agente de estrutura. Se você mesmo estiver montando, chame `mountA2A()` em um plugin de servidor:
+
+```ts
+// server/plugins/a2a.ts
+import { mountA2A } from "@agent-native/core/a2a";
+
+export default defineNitroPlugin((nitro) => {
+  mountA2A(nitro, {
+    name: "Analytics Agent",
+    description: "Runs analytics queries and returns chart data",
+    skills: [
+      {
+        id: "run-query",
+        name: "Run Query",
+        description: "Execute a SQL query against the analytics database",
+        tags: ["analytics", "sql"],
+        examples: ["Show me signups by source this month"],
+      },
+    ],
+    // Optional legacy external-peer bearer key. Prefer A2A_SECRET for
+    // agent-native workspace calls and production deployments.
+    apiKeyEnv: "A2A_API_KEY",
+    streaming: true, // enable message/stream
+  });
+});
+```
+
+Isso monta:
+
+- `GET /.well-known/agent-card.json` — metadados de descoberta pública.
+- `POST /_agent-native/a2a` — endpoint JSON-RPC nativo do agente primário.
+- `POST /_agent-native/a2a/_process-task` — rota interna do processador assíncrono, assinada com `A2A_SECRET`.
+
+O cliente também recorre a `/a2a` para agentes externos que expõem o caminho herdado/simples. As implantações nativas do agente de produção devem definir `A2A_SECRET`; sem ele, os tempos de execução hospedados falham no fechamento em vez de aceitar trabalho remoto não autenticado.
+
+## Cartão de agente {#agent-card}
+
+O cartão do agente é gerado automaticamente a partir da sua configuração e servido em `/.well-known/agent-card.json`. Outros agentes o buscam para descobrir o skills do seu agente.
+
+### Filtragem de habilidades por locatário {#agent-card-filtering}
+
+O endpoint do cartão é público, portanto, a estrutura edita skills cujos IDs revelam integrações por usuário ou por organização antes de servi-lo. Qualquer habilidade cujo id comece com `mcp__user_<emailhash>_…` ou `mcp__org_<orgid>_…` é retirada da carta publicada. As ferramentas stdio MCP controladas pelo operador (carregadas do `mcp.config.json`) e o skills definido pelo modelo permanecem visíveis. Isso evita que um chamador não autenticado registre as impressões digitais de quais locatários existem ou quais integrações eles conectaram. Consulte `packages/core/src/a2a/server.ts`.
+
+```json
+{
+  "name": "Analytics Agent",
+  "description": "Runs analytics queries and returns chart data",
+  "url": "https://analytics.example.com",
+  "version": "1.0.0",
+  "protocolVersion": "0.3",
+  "capabilities": {
+    "streaming": true,
+    "pushNotifications": false,
+    "stateTransitionHistory": true
+  },
+  "skills": [
+    {
+      "id": "run-query",
+      "name": "Run Query",
+      "description": "Execute a SQL query against the analytics database",
+      "tags": ["analytics", "sql"],
+      "examples": ["Show me signups by source this month"]
+    }
+  ],
+  "securitySchemes": {
+    "jwtBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" },
+    "apiKey": { "type": "http", "scheme": "bearer" }
+  },
+  "security": [{ "jwtBearer": [] }, { "apiKey": [] }]
+}
+```
+
+_(A versão pode ser diferente; busque o cartão ativo do seu aplicativo em `/.well-known/agent-card.json` para o `protocolVersion` atual.)_
+
+Quando `A2A_SECRET` está definido (o caminho recomendado), a placa anuncia um
+Esquema `jwtBearer` como acima. O esquema `apiKey` só é adicionado quando um legado
+`apiKeyEnv` também é configurado, então um cartão com apenas `A2A_SECRET` definido é publicado
+`jwtBearer` sozinho.
+
+## Métodos JSON-RPC {#json-rpc-methods}
+
+Todos os métodos são chamados via `POST /_agent-native/a2a` com formato JSON-RPC 2.0:
+
+| Método           | Descrição                                                                                                                            | Parâmetros-chave              |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------- |
+| `message/send`   | Envie uma mensagem e aguarde a conclusão da tarefa. Passe `async: true` para retornar imediatamente ao estado `working` e pesquisar. | `message, contextId?, async?` |
+| `message/stream` | Envie uma mensagem e receba atualizações de tarefas SSE                                                                              | `message, contextId?`         |
+| `tasks/get`      | Buscar uma tarefa por ID — usado para pesquisar uma tarefa assíncrona até a conclusão                                                | `id`                          |
+| `tasks/cancel`   | Cancelar uma tarefa em execução                                                                                                      | `id`                          |
+
+```an-api title="Primary A2A endpoint" summary="All JSON-RPC methods are POSTed here. message/send shown."
+{
+  "method": "POST",
+  "path": "/_agent-native/a2a",
+  "summary": "Send a message and wait for the completed task",
+  "description": "JSON-RPC 2.0 endpoint for `message/send`, `message/stream`, `tasks/get`, and `tasks/cancel`. Pass `async: true` to return immediately in `working` state and poll with `tasks/get`.",
+  "auth": "JWT bearer signed with A2A_SECRET (or legacy apiKeyEnv static token)",
+  "params": [
+    { "name": "Authorization", "in": "header", "type": "string", "required": false, "description": "Bearer token. Required in hosted production runtimes; optional in local dev." },
+    { "name": "method", "in": "body", "type": "string", "required": true, "description": "One of message/send, message/stream, tasks/get, tasks/cancel." },
+    { "name": "params.message", "in": "body", "type": "object", "required": false, "description": "{ role, parts[] } for message/send and message/stream." },
+    { "name": "params.async", "in": "body", "type": "boolean", "required": false, "description": "Return immediately in working state and poll via tasks/get. Use on serverless hosts." },
+    { "name": "params.id", "in": "body", "type": "string", "required": false, "description": "Task id for tasks/get and tasks/cancel." }
+  ],
+  "request": {
+    "contentType": "application/json",
+    "example": "{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"message/send\",\n  \"params\": {\n    \"message\": {\n      \"role\": \"user\",\n      \"parts\": [{ \"type\": \"text\", \"text\": \"Show signups by source\" }]\n    },\n    \"async\": true\n  }\n}"
+  },
+  "responses": [
+    { "status": "200", "description": "JSON-RPC result containing the task. With async:true the task returns in working state.", "example": "{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"result\": { \"id\": \"task_123\", \"status\": { \"state\": \"working\" } }\n}" },
+    { "status": "503", "description": "Hosted production runtime with no A2A_SECRET configured — fails closed instead of running unauthenticated." }
+  ]
+}
+```
+
+Quando `message/send` é chamado com `async: true`, o manipulador JSON-RPC enfileira a tarefa e dispara automaticamente um POST para uma rota interna `/_agent-native/a2a/_process-task` para que o manipulador seja executado em uma nova execução de função com seu próprio tempo limite completo. Esta rota é autenticada com um token HMAC vinculado ao ID da tarefa (tempo de vida de 5 minutos, assinado com `A2A_SECRET`). Ele é montado antes da rota `/_agent-native/a2a` JSON-RPC para que a correspondência de prefixo de h3 não o engula.
+
+```an-diagram title="Async task lifecycle on serverless" summary="async:true returns working in milliseconds, then a fresh execution runs the agent loop while the caller polls."
+{
+  "html": "<div class=\"diagram-async\"><div class=\"diagram-box\" data-rough>message/send<br><small class=\"diagram-muted\">async: true</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\"><span class=\"diagram-pill\">enqueue task</span><span class=\"diagram-pill warn\">return working</span><small class=\"diagram-muted\">~milliseconds</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>self-fire POST /_agent-native/a2a/_process-task<br><small class=\"diagram-muted\">HMAC token · fresh execution · full timeout</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill\">tasks/get (poll)</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">completed</div></div></div>",
+  "css": ".diagram-async{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-async .diagram-panel{display:flex;flex-direction:column;align-items:center;gap:6px}.diagram-async .diagram-col{display:flex;flex-direction:column;align-items:center;gap:6px}.diagram-async .diagram-arrow{font-size:20px;line-height:1}",
+  "caption": "A recurring sweeper re-claims any task left in flight if the function execution dies mid-run."
+}
+```
+
+> [!IMPORTANT]
+> **Tempos limite de webhook e gateway sem servidor:**
+> Gateways de ambiente hospedado (como Netlify, Vercel ou Cloudflare Pages) impõem limites de execução rígidos (geralmente de 10 a 30 segundos) em rotas HTTP públicas. Como os loops de agente podem levar um tempo significativo para executar consultas, buscar contexto e executar ferramentas, você **deve usar `async: true`** ao chamar endpoints A2A ou manipular webhooks externo. Isso retorna imediatamente um status `working` para o gateway API, mantendo a conexão aberta apenas por alguns milissegundos, enquanto o `/process-task` POST autoacionado executa o loop do agente em segundo plano. Não bloqueie a solicitação HTTP primária aguardando a conclusão do loop do agente.
+
+As mensagens contêm partes digitadas — texto, dados estruturados e arquivos podem viajar em uma única mensagem:
+
+```an-annotated-code title="A2A message with typed parts"
+{
+  "language": "json",
+  "code": "{\n  \"role\": \"user\",\n  \"parts\": [\n    { \"type\": \"text\", \"text\": \"Show signups by source\" },\n    { \"type\": \"data\", \"data\": { \"dateRange\": \"last-30d\" } },\n    {\n      \"type\": \"file\",\n      \"file\": { \"name\": \"report.csv\", \"mimeType\": \"text/csv\", \"bytes\": \"...\" }\n    }\n  ]\n}",
+  "annotations": [
+    { "lines": "4", "label": "text part", "note": "Plain natural-language instruction the agent reads." },
+    { "lines": "5", "label": "data part", "note": "Structured JSON arguments — e.g. a date range — passed alongside the prompt." },
+    { "lines": "6-9", "label": "file part", "note": "Attach a file by name, `mimeType`, and base64 `bytes`." }
+  ]
+}
+```
+
+## Cliente {#client}
+
+A classe `A2AClient` lida com descoberta, mensagens e streaming:
+
+```ts
+import { A2AClient } from "@agent-native/core/a2a";
+
+const client = new A2AClient("https://analytics.example.com", "my-api-key");
+
+// Discover agent capabilities
+const card = await client.getAgentCard();
+console.log(card.skills);
+
+// Send a message and get a completed task
+const task = await client.send({
+  role: "user",
+  parts: [{ type: "text", text: "Show signups by source this month" }],
+});
+console.log(task.status.state); // "completed"
+// task.status.message is a Message object ({ role, parts }), not a string.
+// Pull text out of its parts:
+const reply = task.status.message?.parts
+  .filter((p) => p.type === "text")
+  .map((p) => p.text)
+  .join("");
+console.log(reply); // agent's response text
+
+// Stream responses for long-running work
+for await (const update of client.stream({
+  role: "user",
+  parts: [{ type: "text", text: "Generate a full quarterly report" }],
+})) {
+  console.log(update.status.state, update.status.message);
+}
+```
+
+## Ajudante de conveniência {#convenience-helper}
+
+Para chamadas simples de entrada/saída de texto, use `callAgent()`:
+
+```ts
+import { callAgent } from "@agent-native/core/a2a";
+
+// One-shot: send text, get text back
+const response = await callAgent(
+  "https://analytics.example.com",
+  "How many signups last week?",
+  { apiKey: process.env.ANALYTICS_API_KEY },
+);
+console.log(response); // "There were 1,247 signups last week..."
+```
+
+## Invocação programática do espaço de trabalho {#programmatic-invoke}
+
+Para espaços de trabalho nativos do agente, prefira o auxiliar `agentNative` ao codificar ou um
+o aplicativo headless precisa descobrir aplicativos irmãos e invocá-los por ID, nome ou
+URL. Ele usa as mesmas primitivas de descoberta e invocação A2A que o
+Comandos `agent-native agents` e `agent-native invoke` CLI.
+
+```ts
+import { agentNative } from "@agent-native/core/agent-native";
+
+const agents = await agentNative.listAgents();
+
+const result = await agentNative.invoke(
+  "analytics",
+  "Summarize signups by source this month.",
+  { userEmail: "steve@example.com" },
+);
+
+console.log(`Called ${result.target.name}: ${result.responseText}`);
+```
+
+Use isto para miniaplicativos que podem ser compostos: o Dispatch ou um aplicativo orquestrador descobre
+irmãos do espaço de trabalho e, em seguida, invoca o aplicativo especializado que possui o provedor,
+conjunto de dados ou fluxo de trabalho. Em aplicativos nativos de agente de produção, defina `A2A_SECRET` em cada
+ambiente do aplicativo e passe a identidade do chamador (`userEmail`) para que as chamadas de saída sejam
+assinado como tokens ao portador JWT. Use `apiKeyEnv` apenas para pares externos legados que
+espera um token de portador estático. Use actions local em vez de invocar você mesmo.
+
+## Ciclo de vida da tarefa {#task-lifecycle}
+
+Cada mensagem cria uma tarefa que passa por estes estados:
+
+`submitted` → `working` → `completed` | `failed` | `canceled` | `input-required`
+
+`input-required` não é terminal: o manipulador está aguardando mais informações do chamador e a tarefa pode voltar para `working` assim que a entrada chegar.
+
+| Estado           | Significado                                           |
+| ---------------- | ----------------------------------------------------- |
+| `submitted`      | Tarefa criada, na fila para processamento             |
+| `working`        | O manipulador está processando a mensagem             |
+| `completed`      | Manipulador concluído com sucesso                     |
+| `failed`         | O manipulador gerou um erro                           |
+| `canceled`       | A tarefa foi cancelada através de tarefas/cancelar    |
+| `input-required` | O manipulador precisa de mais informações do chamador |
+
+As tarefas persistem na tabela `a2a_tasks` SQL e podem ser recuperadas posteriormente por meio de `tasks/get`.
+
+## Segurança {#security}
+
+Defina `A2A_SECRET` em cada aplicativo de produção que chama ou recebe tráfego A2A. Os chamadores nativos do agente assinam tokens de portador JWT com esse segredo para que os destinatários possam verificar a identidade do chamador antes do início do loop do agente.
+
+Para peers externos que ainda usam um token estático compartilhado, defina `apiKeyEnv` em sua configuração como o nome de uma variável de ambiente que contém o token de portador esperado:
+
+```ts
+// Config
+mountA2A(app, {
+  // ...
+  apiKeyEnv: "A2A_API_KEY", // reads process.env.A2A_API_KEY
+});
+
+// Client calls with the matching key
+const client = new A2AClient(url, process.env.A2A_API_KEY);
+```
+
+O endpoint do cartão do agente é sempre público (sem autenticação) para que outros agentes possam descobrir recursos. O endpoint `/_agent-native/a2a` JSON-RPC aceita tokens de portador JWT assinados por `A2A_SECRET` e também aceita o token herdado `apiKeyEnv` quando configurado. No desenvolvimento local, a autorização pode ser omitida; em tempos de execução de produção hospedados, a autenticação A2A ausente retorna 503 em vez de ser executada sem autenticação.
+
+### Limite da política de autenticação {#auth-policy}
+
+A validação do portador é executada no limite da solicitação — no manipulador JSON-RPC — antes que o loop do agente veja a mensagem. Os auxiliares compartilhados em `packages/core/src/a2a/auth-policy.ts` decidem o que a implantação requer:
+
+- `isA2AProductionRuntime()` retorna `true` no Netlify, AWS Lambda, Cloudflare Pages/Workers, Vercel, Render, Fly e Cloud Run — mesmo quando `NODE_ENV` não é `"production"`. Alguns provedores sem servidor não definem `NODE_ENV` de forma consistente, então a política também lê sinalizadores específicos do provedor.
+- `hasConfiguredA2ASecret()` retorna `true` quando `A2A_SECRET` é definido.
+- `shouldAdvertiseJwtA2AAuth()` é o que o cartão de agente usa para decidir se deve publicar um esquema de segurança `jwtBearer`.
+
+A política de produção é rigorosa: em qualquer tempo de execução de produção, a rota assíncrona `_process-task` se recusa a despachar, a menos que `A2A_SECRET` esteja configurado (retorna 503) e o endpoint JSON-RPC recusa chamadas não autenticadas. O substituto de desenvolvimento (avisar uma vez, permitir) só é acionado quando nenhum sinalizador de produção está definido.
+
+Esse limite é importante porque o loop do agente aceita entrada de formato livre de um chamador remoto. Colocar a verificação ao portador dentro do loop ou confiar em uma ferramenta para aplicá-la permitiria que a injeção de prompt ou um manipulador com erros ignorasse a autenticação. Mantê-lo no limite HTTP significa uma falha de token em curto-circuito antes de qualquer chamada LLM.
+
+A verificação JWT (`verifyA2AToken` em `server.ts`) aceita tokens assinados com o `A2A_SECRET` global ou com um segredo no escopo da organização consultado em SQL por meio da declaração `org_domain` do token e impõe as declarações `aud`/`iss` do próprio token, quando presentes.
+
+## Continuações {#continuations}
+
+Quando um agente chama um peer A2A remoto que não retorna imediatamente, a estrutura pesquisa `tasks/get` até que a tarefa seja resolvida. Isso é conectado por meio de `A2AClient.sendAndWait`, que é o modo padrão usado pelo auxiliar `callAgent()`.
+
+```ts
+// Default: async + poll (safe on serverless hosts)
+const reply = await callAgent(url, "Generate the quarterly report", {
+  userEmail: session.email,
+});
+
+// Single-shot blocking POST (avoid on Netlify/Vercel for slow handlers)
+const reply2 = await callAgent(url, "Quick lookup", { async: false });
+```
+
+Para continuações de entrada acionadas por uma integração de mensagens (Slack, email), a estrutura persiste a continuação em SQL e a processa fora da banda:
+
+- Uma linha é gravada na tabela `a2a_continuations` quando o manipulador de integração é transferido para um agente remoto.
+- Um `POST /_agent-native/integrations/process-a2a-continuation` auto-disparado reivindica a linha, chama `tasks/get` no agente remoto e entrega a resposta ao adaptador de integração ou reprograma.
+- Se a tarefa remota ainda estiver funcionando, a linha será reprogramada e reenviada. O orçamento da pesquisa é **limitado por aproximadamente 20 minutos de trabalho remoto** (`MAX_REMOTE_WORK_MS`) e **30 tentativas de envio** (`MAX_ATTEMPTS`); após qualquer limite, a continuação falha com um erro claro e o usuário recebe uma resposta "o agente não respondeu a tempo".
+- Um varredor recorrente (`claimDueA2AContinuations`) recupera quaisquer linhas de continuação que foram deixadas em andamento quando a execução da função anterior foi interrompida. Mesmo que o aplicativo de chamada trave no meio da pesquisa, o próximo tick de varredura retoma o trabalho.
+
+Definido em `packages/core/src/integrations/a2a-continuation-processor.ts`. O mesmo padrão de trabalho de nova tentativa é usado para tarefas de webhook de integração (`pending-tasks-retry-job.ts`), que é uma fila distinta limitada a três tentativas, separada do orçamento de pesquisa de continuação acima.
+
+## Espaço de trabalho A2A {#workspace-a2a}
+
+Em um espaço de trabalho com vários aplicativos implantado em um único site Netlify (consulte [multi-app workspace](/docs/multi-app-workspace)), cada aplicativo em `apps/<id>/` é registrado automaticamente como um par A2A:
+
+- Um `A2A_SECRET` compartilhado é montado no ambiente de cada aplicativo no momento da compilação.
+- As chamadas entre aplicativos têm a mesma origem — `https://workspace.example.com/apps/analytics` chama `https://workspace.example.com/apps/mail` — portanto, não há configuração de DNS, CORS ou JWT por par.
+- As chamadas de saída assinadas com o segredo compartilhado carregam o e-mail do chamador como `sub` e (quando presente) o domínio da organização. O verificador JWT do destinatário aceita o segredo compartilhado ou o segredo com escopo organizacional de SQL, nessa ordem.
+- A descoberta do agente percorre o registro do espaço de trabalho em vez de depender do operador para conectar cada par manualmente. Consulte `discoverAgents` em `packages/core/src/server/agent-discovery.ts` e o caminho de atualização da organização em `packages/core/src/org/handlers.ts`.
+
+A2A externo — chamadas para agentes fora do seu espaço de trabalho — ainda usa o modelo de token de portador (`apiKeyEnv` + `A2AClient(url, apiKey)`). O espaço de trabalho A2A está em camadas na parte superior; nada muda nos pares externos.
+
+## Dicas sem servidor {#serverless}
+
+**Nunca confie em um `Promise` do tipo "dispare e esqueça" que sobrevive à resposta.** Funções sem servidor (Netlify, Vercel, AWS Lambda, Cloud Run) congelam no momento em que o corpo da resposta é liberado - às vezes antes mesmo que o handshake TCP de um `fetch(...)` inesperado seja concluído. Os padrões que funcionam localmente no Node eliminarão silenciosamente o trabalho na produção.
+
+O padrão da estrutura, usado tanto pelo despacho assíncrono A2A quanto pelo [integration webhook queue](/docs/messaging), é:
+
+1. Aceite a solicitação, persista o que precisa acontecer com SQL, retorne 200 imediatamente.
+2. Dispare automaticamente um `POST` para uma rota de estrutura separada (`/_agent-native/a2a/_process-task` ou `/_agent-native/integrations/process-task`) para que o trabalho real seja executado em uma **nova execução de função** com seu próprio tempo limite completo.
+3. Autentique o disparo automático com um token HMAC vinculado ao ID da linha, assinado com `A2A_SECRET`.
+4. Um trabalho de repetição recorrente varre todas as linhas que foram reivindicadas, mas não concluídas, para que uma função com falha não atrapalhe o trabalho.
+
+Ao escrever seu próprio manipulador A2A ou adaptador de integração, siga o mesmo formato. Não anexe o trabalho a uma promessa independente após `return`. Se você precisar disparar automaticamente a partir de um manipulador sem servidor, inicie a busca antes de retornar e dê uma pequena vantagem inicial (a estrutura usa um tempo limite curto) para que os tempos de execução no estilo Lambda não congelem antes que a solicitação de saída saia do processo. A habilidade `integration-webhooks` é a referência canônica.
+
+## Menções do agente {#agent-mentions}
+
+Você pode mencionar agentes `@` diretamente no compositor do chat. Agentes conectados usam A2A: quando você menciona um agente conectado, o servidor faz uma chamada A2A para esse agente e integra a resposta no contexto da conversa.
+
+Os agentes de espaço de trabalho personalizados são diferentes: eles são executados localmente dentro do aplicativo/tempo de execução atual, e não em A2A.
+
+Consulte [Agent Mentions](/docs/agent-mentions) para obter detalhes sobre como funcionam as menções, como adicionar agentes e como criar provedores de menções personalizados.
+
+## Integrações de mensagens {#messaging-integrations}
+
+Os agentes também podem ser contatados por meio de plataformas de mensagens externas como Slack, e-mail, Telegram e WhatsApp. Os usuários enviam mensagens nessas plataformas e o agente responde no mesmo tópico, usando as mesmas ferramentas e actions do web chat.
+
+Consulte [Messaging](/docs/messaging) para obter detalhes de configuração em cada plataforma.
+
+## Exemplo: consulta entre agentes {#example}
+
+Um agente de e-mail precisa de dados analíticos. O agente de análise expõe uma habilidade de "consulta de execução" por meio de A2A:
+
+```ts
+// In the mail agent's actions/get-analytics.ts
+import { defineAction } from "@agent-native/core/action";
+import { callAgent } from "@agent-native/core/a2a";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Ask the analytics agent a question.",
+  schema: z.object({ question: z.string() }),
+  async run({ question }) {
+    const response = await callAgent(
+      "https://analytics.example.com",
+      question,
+      { apiKey: process.env.ANALYTICS_API_KEY },
+    );
+    return { answer: response };
+  },
+});
+```
+
+O agente analítico recebe a mensagem, executa a consulta por meio de seu manipulador e retorna o resultado. A ação mail obtém a resposta de texto de volta. Sem banco de dados compartilhado, sem chamadas API diretas — apenas comunicação entre agentes.