@runtypelabs/a2a-aisdk-example 0.0.1 → 0.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Runtype Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,375 @@
+# @runtypelabs/a2a-aisdk-example
+
+Reference A2A agent implementation with **deterministic time tools** and LLM-powered chat.
+
+## Why time tools?
+
+LLMs can't reliably:
+
+- Tell you what day "next Tuesday" is
+- Calculate dates ("30 days from now")
+- Convert timezones correctly
+- Know what time it is
+
+This agent includes deterministic time skills that compute answers from the system clock — no generation, no hallucination. Other agents can call these tools via A2A to get reliable temporal data.
+
+## Quick Start
+
+### Run an A2A Server (Echo Mode - for testing)
+
+```bash
+# Using CLI
+npx @runtypelabs/a2a-aisdk-example serve --echo
+```
+
+This starts a server at:
+
+- Agent Card: `http://localhost:9999/.well-known/agent.json`
+- A2A Endpoint: `http://localhost:9999/a2a`
+
+### Test a time skill
+
+```bash
+curl -X POST http://localhost:9999/a2a \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "tasks/send",
+    "params": {
+      "skill": "time/day_of_week",
+      "message": {
+        "role": "user",
+        "parts": [{"type": "data", "data": {"date": "2025-02-04"}}]
+      }
+    }
+  }'
+# Returns: { "result": { "day": "Tuesday", ... }, "computed": { "method": "deterministic" } }
+```
+
+### Run with LLM
+
+```bash
+# OpenAI
+OPENAI_API_KEY=sk-xxx npx @runtypelabs/a2a-aisdk-example serve
+
+# Anthropic
+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
+
+# Or with LLM (requires OPENAI_API_KEY or ANTHROPIC_API_KEY)
+OPENAI_API_KEY=sk-xxx npx @runtypelabs/a2a-aisdk-example serve
+```
+
+**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 @runtypelabs/a2a-aisdk-example test-runtype \
+  --product-id prod_xxx \
+  --surface-id surf_xxx \
+  --api-key a2a_xxx \
+  --environment local \
+  --message "Hello!"
+```
+
+## Available Skills
+
+### Time Tools (Deterministic)
+
+| Skill                | Description                           |
+| -------------------- | ------------------------------------- |
+| `time/now`           | Current time with timezone            |
+| `time/parse`         | Parse "next Tuesday 3pm" to timestamp |
+| `time/convert`       | Convert between timezones             |
+| `time/add`           | Add days/weeks/months to a date       |
+| `time/diff`          | Duration between two dates            |
+| `time/day_of_week`   | What day is this date?                |
+| `time/is_past`       | Is this timestamp in the past?        |
+| `time/business_days` | Add/subtract business days            |
+
+### General (LLM-Powered)
+
+| Skill     | Description          |
+| --------- | -------------------- |
+| `chat`    | Conversational AI    |
+| `analyze` | Content analysis     |
+| `echo`    | Echo input (testing) |
+
+`chat` can invoke skills tagged with `tool` (for example the deterministic `time/*` skills) through AI SDK tool calling.
+
+Time tools return structured responses with a `computed.method: "deterministic"` field and `usage: "Use this value directly. Do not recalculate."` guidance for calling agents.
+
+Example prompt that triggers tool use from `chat`:
+
+```bash
+npx @runtypelabs/a2a-aisdk-example test http://localhost:9999 \
+  --skill chat \
+  --message "What day of the week is 2026-02-09 in UTC?"
+```
+
+## Connecting to Runtype
+
+### As an External Agent
+
+1. Start the A2A server:
+
+   ```bash
+   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`
+     - A2A Endpoint URL: `http://localhost:9999/a2a`
+   - Click "Connect & Add"
+
+### Testing Runtype's A2A Surface
+
+1. Create an A2A Surface in Runtype Dashboard
+2. Add capabilities (flows) to the surface
+3. Generate an API key for the surface
+4. Test with the CLI:
+   ```bash
+   npx @runtypelabs/a2a-aisdk-example test-runtype \
+     --product-id prod_xxx \
+     --surface-id surf_xxx \
+     --api-key a2a_xxx \
+     --environment local
+   ```
+
+## Programmatic Usage
+
+### Create a Server
+
+```typescript
+import { createA2AServer } from '@runtypelabs/a2a-aisdk-example'
+
+const server = createA2AServer({
+  config: {
+    name: 'My Agent',
+    description: 'A helpful AI assistant',
+    port: 9999,
+  },
+  llmConfig: {
+    provider: 'openai',
+    model: 'gpt-4o-mini',
+    temperature: 0.7,
+  },
+})
+
+await server.start()
+
+// Graceful shutdown
+process.on('SIGINT', async () => {
+  await server.stop()
+})
+```
+
+### Create a Client
+
+```typescript
+import { A2AClient } from '@runtypelabs/a2a-aisdk-example'
+
+const client = new A2AClient({
+  baseUrl: 'http://localhost:9999',
+})
+
+// Get agent card
+const agentCard = await client.getAgentCard()
+console.log(
+  'Skills:',
+  agentCard.skills.map((s) => s.name)
+)
+
+// Send a task
+const task = await client.sendTask({
+  skill: 'chat',
+  message: {
+    role: 'user',
+    parts: [{ type: 'text', text: 'Hello!' }],
+  },
+})
+
+console.log('Response:', task.artifacts?.[0]?.parts?.[0]?.text)
+```
+
+### Test Runtype Surface
+
+```typescript
+import { createRuntypeA2AClient } from '@runtypelabs/a2a-aisdk-example'
+
+const client = createRuntypeA2AClient({
+  productId: 'prod_xxx',
+  surfaceId: 'surf_xxx',
+  apiKey: 'a2a_xxx',
+  environment: 'local', // or 'staging', 'production'
+})
+
+// Send streaming task
+await client.sendTaskStreaming(
+  {
+    skill: 'my-capability',
+    message: {
+      role: 'user',
+      parts: [{ type: 'text', text: 'Analyze this data...' }],
+    },
+  },
+  {
+    onChunk: (text) => process.stdout.write(text),
+    onStatus: (status) => console.log('Status:', status),
+  }
+)
+```
+
+## CLI Reference
+
+Run `npx @runtypelabs/a2a-aisdk-example --help` for all commands and options.
+
+### `serve` - Start A2A Server
+
+```
+Usage: a2a-aisdk-example serve [options]
+
+Options:
+  -p, --port <port>          Port to listen on (default: "9999")
+  -h, --host <host>          Host to bind to (default: "localhost")
+  -n, --name <name>          Agent name (default: "Example A2A Agent")
+  --echo                     Run in echo mode (no LLM, for testing)
+  --provider <provider>      LLM provider: openai, anthropic (default: "openai")
+  --model <model>            LLM model (default: "gpt-4o-mini")
+  --temperature <temp>       LLM temperature (default: "0.7")
+```
+
+### `test` - Test A2A Endpoint
+
+```
+Usage: a2a-aisdk-example test [options] <url>
+
+Arguments:
+  url                   Base URL of the A2A endpoint
+
+Options:
+  -s, --skill <skill>   Skill to test (default: "echo")
+  -m, --message <msg>   Message to send (default: "Hello from A2A client!")
+  --stream              Use streaming mode
+  -k, --api-key <key>   API key for authentication
+```
+
+### `test-runtype` - Test Runtype A2A Surface
+
+```
+Usage: a2a-aisdk-example test-runtype [options]
+
+Options:
+  --product-id <id>     Runtype product ID (required)
+  --surface-id <id>     Runtype surface ID (required)
+  --api-key <key>       A2A API key (required)
+  -e, --environment     Environment: production, staging, local (default: "local")
+  -s, --skill <skill>   Skill/capability to test
+  -m, --message <msg>   Message to send (default: "Hello from A2A client!")
+  --stream              Use streaming mode
+```
+
+## A2A Protocol
+
+This package implements [A2A Protocol v0.3](https://a2aproject.github.io/A2A/specification/).
+
+### Endpoints
+
+- `GET /.well-known/agent.json` - Agent Card discovery
+- `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
+
+## Vercel Deployment
+
+Deploy your A2A agent to Vercel for serverless operation.
+
+### Option 1: Deploy the `vercel-app` directory
+
+1. In Vercel dashboard, set **Root Directory** to `vercel-app`
+2. Add environment variables:
+   - `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`
+   - `AGENT_NAME` (optional)
+   - `ECHO_MODE=true` for testing without LLM
+3. Deploy
+
+### Option 2: Add to Existing Next.js App
+
+Install the package and use the Vercel handlers:
+
+```typescript
+// app/api/a2a/route.ts
+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-aisdk-example/vercel'
+
+export const GET = createAgentCardHandler({
+  name: 'My Agent',
+  llmConfig: { provider: 'openai', model: 'gpt-4o-mini' },
+})
+```
+
+### Serverless Limitations
+
+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
+
+## Development
+
+```bash
+# Build
+pnpm build
+
+# Development mode (watch)
+pnpm dev
+
+# Type check
+pnpm typecheck
+
+# Clean
+pnpm clean
+```
+
+## License
+
+MIT