npm package: @runtypelabs/timely-a2a
Description: Timely - Time-focused A2A agent with deterministic time tools and LLM-powered time chat
Author: Runtype
Latest version: 0.4.3

# Timely (@runtypelabs/timely-a2a)

Time-focused A2A agent with **deterministic time tools** and LLM-powered time chat.

## What is Timely?

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

Timely is an A2A agent that solves this with deterministic time skills that compute answers from the system clock — no generation, no hallucination. The `chat` skill is restricted to time, date, timezone, and scheduling questions, using tool-calling to invoke the deterministic time tools. 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/timely-a2a serve --echo
```

This starts a server at:

- Agent Card: `http://localhost:9999/.well-known/agent-card.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": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"data": {"date": "2025-02-04"}}]
      },
      "metadata": { "skill": "time/day_of_week" }
    }
  }'
```

Returns:
```bash
{ "result": { "day": "Tuesday", ... }, "computed": { "method": "deterministic" } }
```

### Run with LLM

Uses [Vercel AI Gateway](https://sdk.vercel.ai/docs/ai-sdk-core/gateway) to access any model provider through a single API key.

```bash
# Vercel AI Gateway (recommended — supports any provider)
AI_GATEWAY_API_KEY=xxx npx @runtypelabs/timely-a2a serve
```

The default model is `alibaba/qwen3.5-flash`. Use `--model` to switch:

```bash
AI_GATEWAY_API_KEY=xxx npx @runtypelabs/timely-a2a serve --model openai/gpt-4o-mini
```

<details>
<summary>Direct provider fallback (without AI Gateway)</summary>

```bash
# OpenAI
OPENAI_API_KEY=sk-xxx npx @runtypelabs/timely-a2a serve --model gpt-4o-mini --provider openai

# Anthropic
ANTHROPIC_API_KEY=sk-xxx npx @runtypelabs/timely-a2a serve --model claude-sonnet-4-6 --provider anthropic
```

Direct provider mode only supports `openai` and `anthropic` providers, and the model name must not contain a `/` prefix.

</details>

### 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/timely-a2a serve --echo
```

```bash
# Or with LLM (requires AI_GATEWAY_API_KEY)
AI_GATEWAY_API_KEY=xxx npx @runtypelabs/timely-a2a serve
```

**Terminal 2** — run the test:

```bash
# Test echo (works with echo mode)
npx @runtypelabs/timely-a2a test http://localhost:9999

# Test with streaming (chat requires LLM mode + API key)
npx @runtypelabs/timely-a2a test http://localhost:9999 --stream --skill chat --message "What time is it in Tokyo?"
```

> Run `npx @runtypelabs/timely-a2a --help` to see all commands and options.

### Test Runtype A2A Surface

```bash
npx @runtypelabs/timely-a2a 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            |

### Time Chat (LLM-Powered)

| Skill  | Description                                                             |
| ------ | ----------------------------------------------------------------------- |
| `chat` | Conversational assistant for time, date, timezone, and scheduling questions |
| `echo` | Echo input (testing)                                                    |

`chat` can invoke skills tagged with `tool` (for example the deterministic `time/*` skills) through AI SDK tool calling. It is restricted to time-related queries and will politely decline off-topic questions.

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/timely-a2a 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/timely-a2a 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-card.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/timely-a2a 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/timely-a2a'

// Requires AI_GATEWAY_API_KEY env var for gateway models (provider/model format)
const server = createA2AServer({
  config: {
    name: 'Timely',
    description: 'Time-focused A2A agent with deterministic time tools and LLM-powered time chat',
    port: 9999,
  },
  llmConfig: {
    provider: 'openai',
    model: 'alibaba/qwen3.5-flash', // gateway model — any provider via Vercel AI Gateway
    temperature: 0.7,
  },
})

await server.start()

// Graceful shutdown
process.on('SIGINT', async () => {
  await server.stop()
})
```

### Create a Client

```typescript
import { A2AClient } from '@runtypelabs/timely-a2a'

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: 'What time is it in Tokyo?' }],
  },
})

console.log('Response:', task.artifacts?.[0]?.parts?.[0]?.text)
```

### Test Runtype Surface

```typescript
import { createRuntypeA2AClient } from '@runtypelabs/timely-a2a'

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: 'What time is it in London?' }],
    },
  },
  {
    onChunk: (text) => process.stdout.write(text),
    onStatus: (status) => console.log('Status:', status),
  }
)
```

## CLI Reference

Run `npx @runtypelabs/timely-a2a --help` for all commands and options.

### `serve` - Start A2A Server

```
Usage: timely-a2a 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: "Timely")
  --echo                     Run in echo mode (no LLM, for testing)
  --provider <provider>      LLM provider: openai, anthropic (default: "openai")
  --model <model>            LLM model (default: "alibaba/qwen3.5-flash")
  --temperature <temp>       LLM temperature (default: "0.7")
```

### `test` - Test A2A Endpoint

```
Usage: timely-a2a 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: timely-a2a 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://a2a-protocol.org/v0.3.0/specification/).

### Endpoints

- `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

| 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

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:
   - `AI_GATEWAY_API_KEY` — Vercel AI Gateway key (recommended)
   - `AGENT_NAME` (optional)
   - `ECHO_MODE=true` for testing without LLM
   - Or use direct provider keys as fallback: `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`
3. Deploy

### Option 2: Add to Existing Next.js App

Install the package and use the Vercel handlers. Set `AI_GATEWAY_API_KEY` in your environment for gateway models:

```typescript
// app/api/a2a/route.ts
import { createA2AHandler } from '@runtypelabs/timely-a2a/vercel'

export const POST = createA2AHandler({
  name: 'Timely',
  llmConfig: { provider: 'openai', model: 'alibaba/qwen3.5-flash' },
})

// app/.well-known/agent-card.json/route.ts
import { createAgentCardHandler } from '@runtypelabs/timely-a2a/vercel'

export const GET = createAgentCardHandler({
  name: 'Timely',
  llmConfig: { provider: 'openai', model: 'alibaba/qwen3.5-flash' },
})
```

### Serverless Limitations

Since Vercel functions are stateless:

- `GetTask` returns "not available" (no task storage)
- `CancelTask` returns "not available" (can't cancel in-flight tasks)
- Use `message/stream` for streaming responses

## Development

```bash
# Build
pnpm build

# Development mode (watch)
pnpm dev

# Type check
pnpm typecheck

# Clean
pnpm clean
```

## License

MIT