@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/ko-KR/a2a-protocol.md

@@ -0,0 +1,392 @@
+---
+title: "A2A 프로토콜"
+description: "JSON-RPC를 통한 에이전트 간 통신: 검색, 메시징, 스트리밍 및 작업 관리."
+---
+
+# A2A 프로토콜
+
+HTTP를 통한 에이전트 간 통신. 상담원은 서로를 발견하고, 메시지를 보내고, 구조화된 결과를 받습니다.
+
+## 개요 {#overview}
+
+A2A(에이전트 대 에이전트)는 에이전트 간 통신을 위한 JSON-RPC 프로토콜입니다. 메일 에이전트는 분석 에이전트에게 쿼리 실행을 요청할 수 있습니다. 캘린더 에이전트는 프로젝트 관리 에이전트에서 이슈를 검색할 수 있습니다. 각 에이전트는 에이전트 카드를 통해 자신의 기능을 공개하고 표준 JSON-RPC 엔드포인트를 통해 작업을 수락합니다.
+
+A2A is the substrate for cross-app delegation in this framework — most prominently for [Dispatch](/docs/dispatch), which routes a single inbound message (Slack, email, etc.) to whichever app in the workspace is best suited to handle it.
+
+주요 개념:
+
+- **에이전트 카드** — skills 및 기능을 설명하는 `/.well-known/agent-card.json`의 공개 메타데이터
+- **JSON-RPC** — 에이전트 네이티브 앱은 `POST /_agent-native/a2a`를 사용합니다. 외부/레거시 피어는 `POST /a2a`를 사용할 수 있습니다
+- **작업** — 각 메시지는 수명 주기(제출됨, 작업 중, 완료됨, 실패, 취소됨)가 있는 작업을 생성합니다.
+- **JWT 전달자 인증** — 프로덕션 A2A에는 `A2A_SECRET` 또는 명시적인 레거시 `apiKeyEnv`가 필요합니다.
+
+```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}"
+}
+```
+
+## 서버 설정 {#server-setup}
+
+대부분의 템플릿은 프레임워크 에이전트 채팅 플러그인을 통해 A2A를 얻습니다. 직접 마운트하는 경우 서버 플러그인에서 `mountA2A()`를 호출하세요:
+
+```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
+  });
+});
+```
+
+다음 마운트:
+
+- `GET /.well-known/agent-card.json` — 공개 검색 메타데이터.
+- `POST /_agent-native/a2a` — 기본 에이전트 기반 JSON-RPC 엔드포인트.
+- `POST /_agent-native/a2a/_process-task` — `A2A_SECRET`로 서명된 내부 비동기 프로세서 경로.
+
+또한 클라이언트는 레거시/단순 경로를 노출하는 외부 에이전트에 대해 `/a2a`로 대체됩니다. 프로덕션 에이전트 기본 배포에서는 `A2A_SECRET`를 설정해야 합니다. 그렇지 않으면 인증되지 않은 원격 작업을 수락하는 대신 호스팅된 런타임이 실패 처리됩니다.
+
+## 에이전트 카드 {#agent-card}
+
+에이전트 카드는 구성에서 자동 생성되어 `/.well-known/agent-card.json`에서 제공됩니다. 다른 에이전트가 이를 가져와 에이전트의 skills를 검색합니다.
+
+### 테넌트별 기술 필터링 {#agent-card-filtering}
+
+카드 엔드포인트는 공개되므로 프레임워크는 이를 제공하기 전에 ID가 사용자별 또는 조직별 통합을 표시하는 skills를 수정합니다. ID가 `mcp__user_<emailhash>_…` 또는 `mcp__org_<orgid>_…`로 시작하는 모든 스킬은 게시된 카드에서 삭제됩니다. 운영자가 제어하는 ​​stdio MCP 도구(`mcp.config.json`에서 로드됨) 및 템플릿 정의 skills는 계속 표시됩니다. 이렇게 하면 인증되지 않은 호출자가 어떤 테넌트가 존재하는지 또는 어떤 통합이 연결되었는지 지문을 채취하는 것을 방지할 수 있습니다. `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": [] }]
+}
+```
+
+_(버전은 다를 수 있습니다. 현재 `protocolVersion`에 대해서는 `/.well-known/agent-card.json`에서 앱의 라이브 카드를 가져오세요.)_
+
+`A2A_SECRET`가 설정되면(권장 경로) 카드는
+`jwtBearer` 방식은 위와 같습니다. `apiKey` 구성표는 레거시
+`apiKeyEnv`도 구성되어 있으므로 `A2A_SECRET` 세트만 있는 카드가 게시됩니다.
+`jwtBearer` 단독.
+
+## JSON-RPC 방법 {#json-rpc-methods}
+
+모든 메소드는 JSON-RPC 2.0 형식의 `POST /_agent-native/a2a`를 통해 호출됩니다.
+
+| 방법             | 설명                                                                                                                 | 주요 매개변수                 |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `message/send`   | 메시지를 보내고 작업이 완료될 때까지 기다립니다. `async: true`를 전달하여 `working` 상태로 즉시 반환하고 폴링합니다. | `message, contextId?, async?` |
+| `message/stream` | 메시지 보내기, SSE 작업 업데이트 받기                                                                                | `message, contextId?`         |
+| `tasks/get`      | ID로 작업 가져오기 — 비동기 작업을 완료하도록 폴링하는 데 사용됩니다.                                                | `id`                          |
+| `tasks/cancel`   | 실행 중인 작업 취소                                                                                                  | `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." }
+  ]
+}
+```
+
+`message/send`가 `async: true`와 함께 호출되면 JSON-RPC 핸들러는 작업을 대기열에 추가하고 POST를 내부 `/_agent-native/a2a/_process-task` 경로로 자체 실행하므로 핸들러는 자체 전체 시간 초과로 새로운 함수 실행에서 실행됩니다. 이 경로는 작업 ID(5분 수명, `A2A_SECRET`로 서명됨)에 바인딩된 HMAC 토큰으로 인증됩니다. `/_agent-native/a2a` JSON-RPC 경로 앞에 마운트되므로 h3의 접두사 일치가 이를 삼키지 않습니다.
+
+```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]
+> **서버리스 웹훅 및 게이트웨이 시간 초과:**
+> 호스팅 환경 게이트웨이(예: Netlify, Vercel 또는 Cloudflare Pages)는 공용 HTTP 경로에 엄격한 실행 제한(보통 10~30초)을 적용합니다. 에이전트 루프는 쿼리를 실행하고, 컨텍스트를 가져오고, 도구를 실행하는 데 상당한 시간이 걸릴 수 있으므로 A2A 엔드포인트를 호출하거나 외부 webhooks를 처리할 때 **`async: true`**를 사용해야 합니다. 그러면 `working` 상태가 API 게이트웨이에 즉시 반환되어 몇 밀리초 동안만 연결이 열린 상태로 유지되는 반면, 자체 실행된 `/process-task` POST는 백그라운드에서 에이전트 루프를 실행합니다. 에이전트 루프가 완료되기를 기다리는 기본 HTTP 요청을 차단하지 마십시오.
+
+메시지에는 입력된 부분이 포함되어 있습니다. 즉, 텍스트, 구조화된 데이터 및 파일이 모두 하나의 메시지로 전달될 수 있습니다.
+
+```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`." }
+  ]
+}
+```
+
+## 클라이언트 {#client}
+
+`A2AClient` 클래스는 검색, 메시징 및 스트리밍을 처리합니다.
+
+```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);
+}
+```
+
+## 편의 도우미 {#convenience-helper}
+
+간단한 텍스트 입력/텍스트 출력 통화의 경우 `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..."
+```
+
+## 프로그래밍 방식 작업공간 호출 {#programmatic-invoke}
+
+에이전트 기본 작업 공간의 경우 코드 또는 작업 시 `agentNative` 도우미를 선호하세요.
+헤드리스 앱은 형제 앱을 검색하고 ID, 이름 또는
+URL.
+`agent-native agents` 및 `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}`);
+```
+
+구성 가능한 미니 앱에 사용: 디스패치 또는 오케스트레이터 앱이 검색
+작업 공간 형제, 그런 다음 공급자를 소유한 전문 앱을 호출합니다.
+데이터세트 또는 워크플로. 프로덕션 에이전트 기반 앱에서 각 항목에 `A2A_SECRET`를 설정하세요.
+앱 환경을 설정하고 발신자 ID(`userEmail`)를 전달하여 아웃바운드 통화가 가능하도록
+JWT 전달자 토큰으로 서명되었습니다. 다음과 같은 레거시 외부 피어에만 `apiKeyEnv`를 사용하세요.
+정적 전달자 토큰이 필요합니다. 자신을 호출하는 대신 로컬 actions를 사용하세요.
+
+## 작업 수명 주기 {#task-lifecycle}
+
+각 메시지는 다음 상태를 거쳐 이동하는 작업을 생성합니다.
+
+`submitted` → `working` → `completed` | `failed` | `canceled` | `input-required`
+
+`input-required`는 비터미널입니다. 핸들러는 호출자로부터 추가 정보를 기다리고 있으며 해당 입력이 도착하면 작업이 `working`로 다시 이동할 수 있습니다.
+
+| 상태             | 의미                                         |
+| ---------------- | -------------------------------------------- |
+| `submitted`      | 작업이 생성되어 처리 대기 중                 |
+| `working`        | 핸들러가 메시지를 처리하는 중                |
+| `completed`      | 핸들러가 성공적으로 완료되었습니다           |
+| `failed`         | 핸들러에서 오류가 발생했습니다               |
+| `canceled`       | 작업/취소를 통해 작업이 취소되었습니다.      |
+| `input-required` | 핸들러는 호출자로부터 추가 정보가 필요합니다 |
+
+작업은 `a2a_tasks` SQL 테이블에 유지되며 나중에 `tasks/get`를 통해 검색할 수 있습니다.
+
+## 보안 {#security}
+
+A2A 트래픽을 호출하거나 수신하는 모든 프로덕션 앱에 `A2A_SECRET`를 설정합니다. 에이전트 기본 발신자는 이 비밀을 사용하여 JWT 전달자 토큰에 서명하므로 수신자는 에이전트 루프가 시작되기 전에 발신자 신원을 확인할 수 있습니다.
+
+여전히 공유 정적 토큰을 사용하는 외부 피어의 경우 구성에서 `apiKeyEnv`를 예상 전달자 토큰이 포함된 환경 변수의 이름으로 설정하세요.
+
+```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);
+```
+
+에이전트 카드 엔드포인트는 항상 공개(인증 없음)이므로 다른 에이전트가 기능을 검색할 수 있습니다. `/_agent-native/a2a` JSON-RPC 엔드포인트는 `A2A_SECRET`가 서명한 JWT 전달자 토큰을 허용하고 구성 시 레거시 `apiKeyEnv` 토큰도 허용합니다. 로컬 개발에서는 인증을 생략할 수 있습니다. 호스팅된 프로덕션 런타임에서 A2A 인증이 누락되면 인증되지 않은 실행 대신 503이 반환됩니다.
+
+### 인증 정책 경계 {#auth-policy}
+
+전달자 검증은 에이전트 루프가 메시지를 보기 전에 JSON-RPC 처리기의 요청 경계에서 실행됩니다. `packages/core/src/a2a/auth-policy.ts`의 공유 도우미는 배포에 필요한 사항을 결정합니다:
+
+- `isA2AProductionRuntime()`는 `NODE_ENV`가 `"production"`가 아닌 경우에도 Netlify, AWS Lambda, Cloudflare Pages/Workers, Vercel, Render, Fly 및 Cloud Run에서 `true`를 반환합니다. 일부 서버리스 제공업체는 `NODE_ENV`를 일관되게 설정하지 않으므로 정책은 제공업체별 플래그도 읽습니다.
+- `A2A_SECRET`가 설정된 경우 `hasConfiguredA2ASecret()`는 `true`를 반환합니다.
+- `shouldAdvertiseJwtA2AAuth()`는 에이전트 카드가 `jwtBearer` 보안 체계 게시 여부를 결정하는 데 사용하는 것입니다.
+
+프로덕션 정책은 엄격합니다. 모든 프로덕션 런타임에서 비동기 `_process-task` 경로는 `A2A_SECRET`가 구성되지 않는 한(503 반환) 발송을 거부하고 JSON-RPC 엔드포인트는 인증되지 않은 호출을 거부합니다. 개발 폴백(한 번 경고, 허용)은 프로덕션 플래그가 설정되지 않은 경우에만 실행됩니다.
+
+에이전트 루프가 원격 호출자의 자유 형식 입력을 허용하기 때문에 이 경계가 중요합니다. 루프 내부에 전달자 검사를 넣거나 이를 시행하는 도구를 사용하면 프롬프트 주입이나 버그가 있는 처리기가 인증을 우회할 수 있습니다. HTTP 경계에 유지한다는 것은 LLM 호출 전에 토큰 오류가 단락됨을 의미합니다.
+
+JWT 확인(`server.ts`의 `verifyA2AToken`)은 전역 `A2A_SECRET` 또는 토큰의 `org_domain` 클레임을 통해 SQL에서 조회된 조직 범위 비밀로 서명된 토큰을 허용하고 토큰의 자체 `aud`/`iss` 클레임이 있는 경우 이를 시행합니다.
+
+## 계속 {#continuations}
+
+에이전트가 즉시 반환되지 않는 원격 A2A 피어를 호출하면 프레임워크는 작업이 완료될 때까지 `tasks/get`를 폴링합니다. 이는 `callAgent()` 도우미가 사용하는 기본 모드인 `A2AClient.sendAndWait`를 통해 연결됩니다.
+
+```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 });
+```
+
+메시징 통합(Slack, 이메일)에 의해 트리거된 인바운드 연속의 경우 프레임워크는 SQL에서 연속을 유지하고 대역 외에서 처리합니다.
+
+- 통합 핸들러가 원격 에이전트에 전달되면 `a2a_continuations` 테이블에 행이 기록됩니다.
+- 자체 실행된 `POST /_agent-native/integrations/process-a2a-continuation`는 행을 요청하고, 원격 에이전트에서 `tasks/get`를 호출하고, 통합 어댑터에 응답을 전달하거나 일정을 변경합니다.
+- 원격 작업이 계속 작동하는 경우 행이 다시 예약되고 다시 전달됩니다. 폴링 예산은 **원격 작업 최대 20분**(`MAX_REMOTE_WORK_MS`) 및 **30회 파견 시도**(`MAX_ATTEMPTS`)로 제한됩니다. 어느 한도 이후에는 명확한 오류와 함께 계속 진행이 실패하고 사용자는 "에이전트가 제 시간에 응답하지 않았습니다"라는 응답을 받습니다.
+- 반복 스위퍼(`claimDueA2AContinuations`)는 이전 함수 실행이 중단되었을 때 비행 중에 남아 있던 연속 행을 회수합니다. 호출 앱이 설문조사 도중에 충돌을 일으키더라도 다음 스윕 틱에서 작업이 재개됩니다.
+
+`packages/core/src/integrations/a2a-continuation-processor.ts`에 정의되어 있습니다. 동일한 재시도 작업 패턴이 통합 웹훅 작업(`pending-tasks-retry-job.ts`)에 사용됩니다. 이는 위의 연속 폴링 예산과는 별도로 3회 시도로 제한되는 고유한 대기열입니다.
+
+## 작업공간 A2A {#workspace-a2a}
+
+In a multi-app workspace deployed to a single Netlify site (see [multi-app workspace](/docs/multi-app-workspace)), every app under `apps/<id>/` is auto-registered as an A2A peer:
+
+- 공유 `A2A_SECRET`는 빌드 시 모든 앱 환경에 마운트됩니다.
+- 교차 앱 호출은 동일한 출처(`https://workspace.example.com/apps/analytics`가 `https://workspace.example.com/apps/mail`를 호출함)이므로 DNS, CORS 또는 쌍별 JWT 설정이 없습니다.
+- 공유 비밀로 서명된 아웃바운드 통화는 발신자의 이메일을 `sub` 및 (있는 경우) 조직 도메인으로 전달합니다. 수신자의 JWT 검증자는 SQL의 공유 비밀 또는 조직 범위 비밀을 순서대로 수락합니다.
+- 에이전트 검색은 운영자가 각 피어를 직접 연결하는 대신 작업 영역 레지스트리를 탐색합니다. `packages/core/src/server/agent-discovery.ts`의 `discoverAgents` 및 `packages/core/src/org/handlers.ts`의 조직 새로 고침 경로를 참조하세요.
+
+외부 A2A(작업 공간 외부의 에이전트에 대한 호출)는 여전히 전달자 토큰 모델(`apiKeyEnv` + `A2AClient(url, apiKey)`)을 사용합니다. Workspace A2A는 맨 위에 계층화되어 있습니다. 외부 피어 변경 사항은 없습니다.
+
+## 서버리스 문제 {#serverless}
+
+**응답보다 오래 지속되는 Fire-and-forget `Promise`에 의존하지 마십시오.** 서버리스 기능(Netlify, Vercel, AWS Lambda, Cloud Run)은 응답 본문이 플러시되는 순간을 정지합니다. 때로는 기다리지 않은 `fetch(...)`의 TCP 핸드셰이크가 완료되기도 전에 말입니다. Node에서 로컬로 작동하는 패턴은 프로덕션에서 자동으로 작업을 중단합니다.
+
+The framework's pattern, used by both A2A async dispatch and the [integration webhook queue](/docs/messaging), is:
+
+1. 요청을 수락하고 SQL에 필요한 작업을 유지하고 즉시 200을 반환합니다.
+2. `POST`를 별도의 프레임워크 경로(`/_agent-native/a2a/_process-task` 또는 `/_agent-native/integrations/process-task`)로 자체 실행하여 실제 작업이 자체 전체 시간 제한이 있는 **새로운 함수 실행**에서 실행됩니다.
+3. `A2A_SECRET`로 서명된 행 ID에 바인딩된 HMAC 토큰을 사용하여 자체 발사를 인증합니다.
+4. 반복적인 재시도 작업은 요청되었지만 완료되지 않은 행을 모두 제거하므로 충돌된 기능으로 인해 작업이 중단되지 않습니다.
+
+자신만의 A2A 핸들러 또는 통합 어댑터를 작성할 때 동일한 형태를 따르십시오. `return` 이후 분리된 Promise에 작업을 첨부하지 마세요. 서버리스 핸들러에서 자체 실행해야 하는 경우 반환하기 전에 가져오기를 시작하고 미리 시작하여(프레임워크는 짧은 시간 초과를 사용함) 아웃바운드 요청이 프로세스를 떠나기 전에 Lambda 스타일 런타임이 정지되지 않도록 합니다. `integration-webhooks` 스킬은 표준 참조입니다.
+
+## 요원 언급 {#agent-mentions}
+
+채팅 작성기에서 직접 상담원을 `@` 언급할 수 있습니다. 연결된 에이전트는 A2A를 사용합니다. 연결된 에이전트를 언급하면 서버는 해당 에이전트에 A2A 호출을 하고 응답을 대화 컨텍스트에 엮습니다.
+
+맞춤 작업공간 에이전트는 다릅니다. A2A를 통하지 않고 현재 앱/런타임 내에서 로컬로 실행됩니다.
+
+See [Agent Mentions](/docs/agent-mentions) for details on how mentions work, how to add agents, and how to create custom mention providers.
+
+## 메시지 통합 {#messaging-integrations}
+
+Slack, 이메일, Telegram 및 WhatsApp과 같은 외부 메시징 플랫폼을 통해서도 상담원에게 연락할 수 있습니다. 사용자는 해당 플랫폼에서 메시지를 보내고 에이전트는 웹 채팅과 동일한 도구 및 actions를 사용하여 동일한 스레드에서 응답합니다.
+
+See [Messaging](/docs/messaging) for setup details on each platform.
+
+## 예: 에이전트 간 쿼리 {#example}
+
+메일 에이전트에는 분석 데이터가 필요합니다. 분석 에이전트는 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 };
+  },
+});
+```
+
+분석 에이전트는 메시지를 수신하고 해당 핸들러를 통해 쿼리를 실행하고 결과를 반환합니다. 메일 작업은 텍스트 응답을 다시 받습니다. 공유 데이터베이스도 없고 직접 API 호출도 없으며 에이전트 간 통신만 가능합니다.