@runtypelabs/a2a-aisdk-example 0.2.3 → 0.3.0

package/README.md

@@ -1,4 +1,4 @@
-# @runtypelabs/a2a-agent-example
+# @runtypelabs/a2a-aisdk-example
 
 Reference A2A agent implementation with **deterministic time tools** and LLM-powered chat.
 
@@ -19,12 +19,12 @@ This agent includes deterministic time skills that compute answers from the syst
 
 ```bash
 # Using CLI
-npx a2a-agent-example serve --echo
+npx @runtypelabs/a2a-aisdk-example serve --echo
 ```
 
 This starts a server at:
 
-- Agent Card: `http://localhost:9999/.well-known/agent.json`
+- Agent Card: `http://localhost:9999/.well-known/agent-card.json`
 - A2A Endpoint: `http://localhost:9999/a2a`
 
 ### Test a time skill
@@ -35,42 +35,64 @@ curl -X POST http://localhost:9999/a2a \
   -d '{
     "jsonrpc": "2.0",
     "id": "1",
-    "method": "tasks/send",
+    "method": "message/send",
     "params": {
-      "skill": "time/day_of_week",
       "message": {
         "role": "user",
-        "parts": [{"type": "data", "data": {"date": "2025-02-04"}}]
-      }
+        "parts": [{"data": {"date": "2025-02-04"}}]
+      },
+      "metadata": { "skill": "time/day_of_week" }
     }
   }'
-# Returns: { "result": { "day": "Tuesday", ... }, "computed": { "method": "deterministic" } }
+```
+
+Returns:
+```bash
+{ "result": { "day": "Tuesday", ... }, "computed": { "method": "deterministic" } }
 ```
 
 ### Run with LLM
 
 ```bash
 # OpenAI
-OPENAI_API_KEY=sk-xxx npx a2a-agent-example serve
+OPENAI_API_KEY=sk-xxx npx @runtypelabs/a2a-aisdk-example serve
 
 # Anthropic
-ANTHROPIC_API_KEY=sk-xxx npx a2a-agent-example serve --provider anthropic --model claude-3-haiku-20240307
+ANTHROPIC_API_KEY=sk-xxx npx @runtypelabs/a2a-aisdk-example serve --provider anthropic --model claude-3-haiku-20240307
 ```
 
 ### Test an A2A Endpoint
 
+The server must be running first. Use two terminals:
+
+**Terminal 1** — start the server:
+
+```bash
+# Echo mode (no API key needed)
+npx @runtypelabs/a2a-aisdk-example serve --echo
+```
+
 ```bash
-# Test local server
-npx a2a-agent-example test http://localhost:9999
+# Or with LLM (requires OPENAI_API_KEY or ANTHROPIC_API_KEY)
+OPENAI_API_KEY=sk-xxx npx @runtypelabs/a2a-aisdk-example serve
+```
 
-# Test with streaming
-npx a2a-agent-example test http://localhost:9999 --stream --skill chat --message "What is AI?"
+**Terminal 2** — run the test:
+
+```bash
+# Test echo (works with echo mode)
+npx @runtypelabs/a2a-aisdk-example test http://localhost:9999
+
+# Test with streaming (chat requires LLM mode + API key)
+npx @runtypelabs/a2a-aisdk-example test http://localhost:9999 --stream --skill chat --message "What is AI?"
 ```
 
+> Run `npx @runtypelabs/a2a-aisdk-example --help` to see all commands and options.
+
 ### Test Runtype A2A Surface
 
 ```bash
-npx a2a-agent-example test-runtype \
+npx @runtypelabs/a2a-aisdk-example test-runtype \
   --product-id prod_xxx \
   --surface-id surf_xxx \
   --api-key a2a_xxx \
@@ -108,7 +130,7 @@ Time tools return structured responses with a `computed.method: "deterministic"`
 Example prompt that triggers tool use from `chat`:
 
 ```bash
-npx a2a-agent-example test http://localhost:9999 \
+npx @runtypelabs/a2a-aisdk-example test http://localhost:9999 \
   --skill chat \
   --message "What day of the week is 2026-02-09 in UTC?"
 ```
@@ -120,14 +142,14 @@ npx a2a-agent-example test http://localhost:9999 \
 1. Start the A2A server:
 
    ```bash
-   npx a2a-agent-example serve --echo --port 9999
+   npx @runtypelabs/a2a-aisdk-example serve --echo --port 9999
    ```
 
 2. In Runtype Dashboard:
    - Go to your Product
    - Click "Add Capability" > "Connect External"
    - Enter:
-     - Agent Card URL: `http://localhost:9999/.well-known/agent.json`
+     - Agent Card URL: `http://localhost:9999/.well-known/agent-card.json`
      - A2A Endpoint URL: `http://localhost:9999/a2a`
    - Click "Connect & Add"
 
@@ -138,7 +160,7 @@ npx a2a-agent-example test http://localhost:9999 \
 3. Generate an API key for the surface
 4. Test with the CLI:
    ```bash
-   npx a2a-agent-example test-runtype \
+   npx @runtypelabs/a2a-aisdk-example test-runtype \
      --product-id prod_xxx \
      --surface-id surf_xxx \
      --api-key a2a_xxx \
@@ -150,7 +172,7 @@ npx a2a-agent-example test http://localhost:9999 \
 ### Create a Server
 
 ```typescript
-import { createA2AServer } from '@runtypelabs/a2a-agent-example'
+import { createA2AServer } from '@runtypelabs/a2a-aisdk-example'
 
 const server = createA2AServer({
   config: {
@@ -176,7 +198,7 @@ process.on('SIGINT', async () => {
 ### Create a Client
 
 ```typescript
-import { A2AClient } from '@runtypelabs/a2a-agent-example'
+import { A2AClient } from '@runtypelabs/a2a-aisdk-example'
 
 const client = new A2AClient({
   baseUrl: 'http://localhost:9999',
@@ -204,7 +226,7 @@ console.log('Response:', task.artifacts?.[0]?.parts?.[0]?.text)
 ### Test Runtype Surface
 
 ```typescript
-import { createRuntypeA2AClient } from '@runtypelabs/a2a-agent-example'
+import { createRuntypeA2AClient } from '@runtypelabs/a2a-aisdk-example'
 
 const client = createRuntypeA2AClient({
   productId: 'prod_xxx',
@@ -231,10 +253,12 @@ await client.sendTaskStreaming(
 
 ## CLI Reference
 
+Run `npx @runtypelabs/a2a-aisdk-example --help` for all commands and options.
+
 ### `serve` - Start A2A Server
 
 ```
-Usage: a2a-agent-example serve [options]
+Usage: a2a-aisdk-example serve [options]
 
 Options:
   -p, --port <port>          Port to listen on (default: "9999")
@@ -249,7 +273,7 @@ Options:
 ### `test` - Test A2A Endpoint
 
 ```
-Usage: a2a-agent-example test [options] <url>
+Usage: a2a-aisdk-example test [options] <url>
 
 Arguments:
   url                   Base URL of the A2A endpoint
@@ -264,7 +288,7 @@ Options:
 ### `test-runtype` - Test Runtype A2A Surface
 
 ```
-Usage: a2a-agent-example test-runtype [options]
+Usage: a2a-aisdk-example test-runtype [options]
 
 Options:
   --product-id <id>     Runtype product ID (required)
@@ -278,20 +302,22 @@ Options:
 
 ## A2A Protocol
 
-This package implements [A2A Protocol v0.3](https://a2aproject.github.io/A2A/specification/).
+This package implements [A2A Protocol v0.3](https://a2a-protocol.org/v0.3.0/specification/).
 
 ### Endpoints
 
-- `GET /.well-known/agent.json` - Agent Card discovery
+- `GET /.well-known/agent-card.json` - Agent Card discovery (also serves `/.well-known/agent.json` for backward compat)
 - `POST /a2a` - JSON-RPC endpoint
 
 ### Supported Methods
 
-- `tasks/send` - Create and execute a task (synchronous)
-- `tasks/sendSubscribe` - Create and execute a task with SSE streaming
-- `tasks/get` - Get task status
-- `tasks/cancel` - Cancel a running task
-- `ping` - Health check
+| Spec Method (preferred) | Legacy Alias | Description |
+| --- | --- | --- |
+| `message/send` | `tasks/send`, `SendMessage` | Send a message (synchronous) |
+| `message/stream` | `tasks/sendSubscribe`, `SendStreamingMessage` | Send a message with SSE streaming |
+| `GetTask` | `tasks/get` | Get task status |
+| `CancelTask` | `tasks/cancel` | Cancel a running task |
+| `ping` | | Health check |
 
 ## Vercel Deployment
 
@@ -312,15 +338,15 @@ Install the package and use the Vercel handlers:
 
 ```typescript
 // app/api/a2a/route.ts
-import { createA2AHandler } from '@runtypelabs/a2a-agent-example/vercel'
+import { createA2AHandler } from '@runtypelabs/a2a-aisdk-example/vercel'
 
 export const POST = createA2AHandler({
   name: 'My Agent',
   llmConfig: { provider: 'openai', model: 'gpt-4o-mini' },
 })
 
-// app/.well-known/agent.json/route.ts
-import { createAgentCardHandler } from '@runtypelabs/a2a-agent-example/vercel'
+// app/.well-known/agent-card.json/route.ts
+import { createAgentCardHandler } from '@runtypelabs/a2a-aisdk-example/vercel'
 
 export const GET = createAgentCardHandler({
   name: 'My Agent',
@@ -332,9 +358,9 @@ export const GET = createAgentCardHandler({
 
 Since Vercel functions are stateless:
 
-- `tasks/get` returns "not available" (no task storage)
-- `tasks/cancel` returns "not available" (can't cancel in-flight tasks)
-- Use `tasks/sendSubscribe` for streaming responses
+- `GetTask` returns "not available" (no task storage)
+- `CancelTask` returns "not available" (can't cancel in-flight tasks)
+- Use `message/stream` for streaming responses
 
 ## Development