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)

# 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

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:

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

Run with LLM

Uses Vercel AI Gateway to access any model provider through a single API key.

# 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:

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

# 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.

Test an A2A Endpoint

The server must be running first. Use two terminals:

Terminal 1 — start the server:

# Echo mode (no API key needed)
npx @runtypelabs/timely-a2a serve --echo

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

Terminal 2 — run the test:

# 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

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:

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:

   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:

   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

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

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

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.

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:

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

# Build
pnpm build

# Development mode (watch)
pnpm dev

# Type check
pnpm typecheck

# Clean
pnpm clean

License

MIT