A2A

Decision

In the wild

Reader gotcha

Implementation sketch

// Community TS SDK exists (`@a2a-js/sdk`); the spec is HTTP+JSON-RPC and works
// with bare `fetch`, which is what the snippet below shows so the wire shape is
// visible without an SDK indirection.

type AgentCard = {
  name: string
  url: string
  capabilities: { skills: { id: string; description: string }[] }
}

type TaskEnvelope = { jsonrpc: '2.0'; id: string; method: 'message/send'; params: unknown }

async function discover(agentUrl: string): Promise<AgentCard> {
  const res = await fetch(`${agentUrl}/.well-known/agent-card.json`)
  if (!res.ok) throw new Error(`Agent discovery failed: ${res.status}`)
  return (await res.json()) as AgentCard
}

async function invoke(agentUrl: string, skillId: string, text: string, token: string): Promise<unknown> {
  const body: TaskEnvelope = {
    jsonrpc: '2.0',
    id: crypto.randomUUID(),
    method: 'message/send',
    params: { skillId, message: { role: 'user', parts: [{ kind: 'text', text }] } },
  }
  const res = await fetch(`${agentUrl}/`, {
    method: 'POST',
    headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
    body: JSON.stringify(body),
  })
  if (!res.ok) throw new Error(`Task failed: ${res.status} ${await res.text()}`)
  return res.json()
}

const card = await discover('https://research-agent.example.com')
if (!card.capabilities.skills.some((s) => s.id === 'literature_search')) {
  throw new Error('Required skill not advertised by remote agent')
}
const result = await invoke('https://research-agent.example.com', 'literature_search', 'agentic design patterns', process.env.A2A_TOKEN!)
console.log(result)

export {}