a2a-nextjs 0.1.0

package/README.md

@@ -0,0 +1,135 @@
+# @adriancooney/a2a-nextjs
+
+A2A protocol handler for Next.js. Translates AI SDK streams to A2A events.
+
+## Installation
+
+```bash
+pnpm add @adriancooney/a2a-nextjs @a2a-js/sdk
+```
+
+## Usage
+
+### Create an agent
+
+```typescript
+// lib/agents/my-agent.ts
+import { createAgent, InMemoryTaskStore } from "@adriancooney/a2a-nextjs"
+
+export const myAgent = createAgent({
+  card: {
+    name: "my-agent",
+    description: "A helpful assistant",
+    skills: [
+      { id: "chat", name: "Chat", description: "General conversation" },
+    ],
+  },
+  taskStore: new InMemoryTaskStore(),
+  execute: async (prompt) => {
+    // Return a ReadableStream<UIMessageChunk>
+  },
+})
+```
+
+### Create routes
+
+```typescript
+// app/api/agent/route.ts
+import { myAgent } from "@/lib/agents/my-agent"
+
+export const POST = myAgent
+```
+
+```typescript
+// app/.well-known/agent.json/route.ts
+import { myAgent } from "@/lib/agents/my-agent"
+
+export const GET = () => Response.json(myAgent.buildCard({ url: "/api/agent" }))
+```
+
+## With Workflow + DurableAgent
+
+```typescript
+// lib/agents/my-agent.ts
+import { createAgent, InMemoryTaskStore } from "@adriancooney/a2a-nextjs"
+import { start, getRun } from "workflow/api"
+import { runAgentWorkflow } from "@/lib/agent"
+
+export const myAgent = createAgent({
+  card: {
+    name: "my-agent",
+    description: "A helpful assistant",
+    skills: [],
+  },
+  taskStore: new InMemoryTaskStore(),
+  execute: async (prompt) => {
+    const run = await start(runAgentWorkflow, [{ prompt }])
+    return getRun(run.runId).getReadable()
+  },
+})
+```
+
+```typescript
+// lib/agent.ts
+import { DurableAgent } from "@workflow/ai/agent"
+import { getWritable } from "workflow"
+import type { UIMessageChunk } from "ai"
+
+export async function runAgentWorkflow({ prompt }: { prompt: string }) {
+  "use workflow"
+
+  const writable = getWritable<UIMessageChunk>()
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-sonnet-4",
+    system: "You are a helpful assistant.",
+    tools: {},
+  })
+
+  await agent.stream({
+    messages: [{ role: "user", content: prompt }],
+    writable,
+  })
+}
+```
+
+## API
+
+### `createAgent(config): AgentHandler`
+
+Creates an agent handler.
+
+**Config:**
+
+- `card` - Agent metadata (name, description, skills)
+- `taskStore` - Task persistence (`InMemoryTaskStore` or custom)
+- `execute` - Returns `ReadableStream<UIMessageChunk>`
+
+**Returns** a callable handler with:
+
+- `(request: Request) => Promise<Response>` - POST handler
+- `.buildCard({ url })` - Build full AgentCard
+
+### Types
+
+```typescript
+interface AgentCardConfig {
+  name: string
+  description: string
+  version?: string
+  protocolVersion?: string
+  skills?: AgentSkillConfig[]
+  capabilities?: Record<string, unknown>
+  defaultInputModes?: string[]
+  defaultOutputModes?: string[]
+}
+
+interface UIMessageChunk {
+  type: string
+  delta?: string
+  toolCallId?: string
+  toolName?: string
+  output?: unknown
+  errorText?: string
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { TaskStore } from '@a2a-js/sdk/server';
+export { InMemoryTaskStore, TaskStore } from '@a2a-js/sdk/server';
+import { AgentCard } from '@a2a-js/sdk';
+export { AgentCard } from '@a2a-js/sdk';
+
+interface UIMessageChunk {
+    type: string;
+    delta?: string;
+    toolCallId?: string;
+    toolName?: string;
+    output?: unknown;
+    errorText?: string;
+}
+interface AgentSkillConfig {
+    id: string;
+    name: string;
+    description?: string;
+    tags?: string[];
+}
+interface AgentCardConfig {
+    name: string;
+    description: string;
+    version?: string;
+    protocolVersion?: string;
+    skills?: AgentSkillConfig[];
+    capabilities?: Record<string, unknown>;
+    defaultInputModes?: string[];
+    defaultOutputModes?: string[];
+}
+interface AgentConfig {
+    card: AgentCardConfig;
+    taskStore: TaskStore;
+    execute: (prompt: string) => Promise<ReadableStream<UIMessageChunk>>;
+}
+interface AgentHandler {
+    (request: Request): Promise<Response>;
+    buildCard(config: {
+        url: string;
+    }): AgentCard;
+}
+declare function createAgent(config: AgentConfig): AgentHandler;
+
+export { type AgentCardConfig, type AgentConfig, type AgentHandler, type AgentSkillConfig, type UIMessageChunk, createAgent };

package/dist/index.js

@@ -0,0 +1,231 @@
+// src/index.ts
+import crypto from "crypto";
+import {
+  DefaultRequestHandler,
+  JsonRpcTransportHandler
+} from "@a2a-js/sdk/server";
+import { InMemoryTaskStore } from "@a2a-js/sdk/server";
+function statusUpdate(taskId, contextId, state, message, final) {
+  return {
+    kind: "status-update",
+    taskId,
+    contextId,
+    status: {
+      state,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...message && {
+        message: {
+          kind: "message",
+          role: "agent",
+          messageId: crypto.randomUUID(),
+          parts: [{ kind: "text", text: message }]
+        }
+      }
+    },
+    final: final ?? false
+  };
+}
+function artifactUpdate(taskId, contextId, artifact) {
+  return {
+    kind: "artifact-update",
+    taskId,
+    contextId,
+    artifact
+  };
+}
+async function translateAIStreamToA2A(stream, taskId, contextId, eventBus) {
+  const reader = stream.getReader();
+  let textBuffer = "";
+  const toolNames = /* @__PURE__ */ new Map();
+  let artifactIndex = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const chunk = value;
+      switch (chunk.type) {
+        case "text-delta":
+          textBuffer += chunk.delta;
+          break;
+        case "tool-input-available":
+          toolNames.set(chunk.toolCallId, chunk.toolName);
+          eventBus.publish(
+            statusUpdate(taskId, contextId, "working", `Calling ${chunk.toolName}`)
+          );
+          break;
+        case "tool-output-available": {
+          const toolName = toolNames.get(chunk.toolCallId) || "tool";
+          let outputText;
+          if (typeof chunk.output === "string") {
+            outputText = chunk.output;
+          } else if (chunk.output?.output?.value) {
+            const value2 = chunk.output.output.value;
+            try {
+              const parsed = JSON.parse(value2);
+              outputText = parsed.output ?? value2;
+            } catch {
+              outputText = value2;
+            }
+          } else if (chunk.output?.output) {
+            const output = chunk.output.output;
+            outputText = typeof output === "string" ? output : JSON.stringify(output, null, 2);
+          } else {
+            outputText = JSON.stringify(chunk.output, null, 2);
+          }
+          eventBus.publish(
+            artifactUpdate(taskId, contextId, {
+              artifactId: `artifact_${chunk.toolCallId}`,
+              name: toolName,
+              description: `Output from ${toolName}`,
+              parts: [{ kind: "text", text: outputText }]
+            })
+          );
+          artifactIndex++;
+          break;
+        }
+        case "tool-output-error":
+          eventBus.publish(
+            artifactUpdate(taskId, contextId, {
+              artifactId: `artifact_error_${chunk.toolCallId}`,
+              name: "error",
+              description: "Tool execution error",
+              parts: [{ kind: "text", text: chunk.errorText || "Unknown error" }]
+            })
+          );
+          artifactIndex++;
+          break;
+        case "error":
+          eventBus.publish(statusUpdate(taskId, contextId, "failed", chunk.errorText, true));
+          eventBus.finished();
+          return;
+      }
+    }
+    reader.releaseLock();
+    if (textBuffer) {
+      eventBus.publish(
+        artifactUpdate(taskId, contextId, {
+          artifactId: `artifact_response_${artifactIndex}`,
+          name: "response",
+          description: "Agent response",
+          parts: [{ kind: "text", text: textBuffer }]
+        })
+      );
+      artifactIndex++;
+    }
+    const hasOutput = artifactIndex > 0;
+    const completionMessage = hasOutput ? void 0 : "Task completed with no output";
+    eventBus.publish(statusUpdate(taskId, contextId, "completed", completionMessage, true));
+    eventBus.finished();
+  } catch (error) {
+    eventBus.publish(statusUpdate(taskId, contextId, "failed", String(error), true));
+    eventBus.finished();
+  }
+}
+function createAIStreamExecutor(execute) {
+  return {
+    async execute(requestContext, eventBus) {
+      const { userMessage, taskId, contextId, task } = requestContext;
+      if (!task) {
+        const initialTask = {
+          kind: "task",
+          id: taskId,
+          contextId,
+          status: {
+            state: "submitted",
+            timestamp: (/* @__PURE__ */ new Date()).toISOString()
+          },
+          history: [userMessage],
+          artifacts: []
+        };
+        eventBus.publish(initialTask);
+      }
+      eventBus.publish(statusUpdate(taskId, contextId, "working"));
+      const prompt = userMessage.parts.filter((p) => p.kind === "text").map((p) => p.text).join("\n");
+      try {
+        const stream = await execute(prompt);
+        await translateAIStreamToA2A(stream, taskId, contextId, eventBus);
+      } catch (error) {
+        eventBus.publish(statusUpdate(taskId, contextId, "failed", String(error), true));
+        eventBus.finished();
+      }
+    },
+    async cancelTask(taskId, eventBus) {
+      eventBus.publish({
+        kind: "status-update",
+        taskId,
+        contextId: "",
+        status: {
+          state: "canceled",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        final: true
+      });
+      eventBus.finished();
+    }
+  };
+}
+function isAsyncGenerator(obj) {
+  return obj !== null && typeof obj === "object" && Symbol.asyncIterator in obj;
+}
+async function* streamToSSE(generator) {
+  const encoder = new TextEncoder();
+  for await (const event of generator) {
+    yield encoder.encode(`data: ${JSON.stringify(event)}
+
+`);
+  }
+}
+function createAgent(config) {
+  const { card, taskStore, execute } = config;
+  function buildCard({ url }) {
+    return {
+      name: card.name,
+      description: card.description,
+      url,
+      version: card.version ?? "1.0.0",
+      protocolVersion: card.protocolVersion ?? "0.2.0",
+      capabilities: card.capabilities ?? {},
+      defaultInputModes: card.defaultInputModes ?? ["text"],
+      defaultOutputModes: card.defaultOutputModes ?? ["text"],
+      skills: (card.skills ?? []).map((s) => ({
+        id: s.id,
+        name: s.name,
+        description: s.description ?? "",
+        tags: s.tags ?? []
+      }))
+    };
+  }
+  const executor = createAIStreamExecutor(execute);
+  const handler = async function handler2(request) {
+    const url = new URL(request.url);
+    const agentCard = buildCard({ url: url.pathname });
+    const requestHandler = new DefaultRequestHandler(agentCard, taskStore, executor);
+    const transport = new JsonRpcTransportHandler(requestHandler);
+    const body = await request.json();
+    const result = await transport.handle(body);
+    if (isAsyncGenerator(result)) {
+      const stream = new ReadableStream({
+        async pull(controller) {
+          for await (const chunk of streamToSSE(result)) {
+            controller.enqueue(chunk);
+          }
+          controller.close();
+        }
+      });
+      return new Response(stream, {
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive"
+        }
+      });
+    }
+    return Response.json(result);
+  };
+  handler.buildCard = buildCard;
+  return handler;
+}
+export {
+  InMemoryTaskStore,
+  createAgent
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "a2a-nextjs",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@a2a-js/sdk": "^0.3.9"
+  },
+  "devDependencies": {
+    "@a2a-js/sdk": "^0.3.9",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  }
+}