​

Defining capabilities

​

The minimum

agent.define_capability({
  name: 'lookup_invoice',
  description: 'Fetch an invoice by its id and return the line items.',
  parameters: {
    type: 'object',
    properties: {
      invoice_id: { type: 'string', description: 'Invoice id (e.g. inv_123)' },
    },
    required: ['invoice_id'],
  },
  handler: async ({ invoice_id }) => {
    const invoice = await db.invoices.find(invoice_id);
    return { invoice };
  },
});

1. name — snake_case, unique per agent. This is what callers and LLMs see.
2. description — what the capability does, written for an LLM. Good descriptions double as good docs.
3. parameters — JSON Schema validated before your handler runs.

​

Writing good schemas

• Every field gets a description. The LLM leans on these more than the types.
• Mark everything the handler can’t synthesize as required. Unmarked optional fields are the common source of “the model never fills this in” bugs.
• Prefer enum over free-form strings when the value is one of a closed set (status: { type: 'string', enum: ['draft', 'sent', 'paid'] }).
• Keep nesting shallow. LLMs are measurably worse at deeply nested objects than at flat ones.

​

The handler

handler: async (args, context) => {
  // args is typed as Record<string, unknown> — cast or validate as needed.
  // context: CapabilitySessionContext (see below).
  return { /* plain JSON-serializable result */ };
}

• Return any JSON-serializable value. It ends up in the DataPart.data.result that callers receive.
• Throwing from the handler surfaces as an A2A error to the caller. Throw Error subclasses with clear messages.
• Long-running work is fine — there’s no hard timeout in the SDK; the platform’s dispatch timeout (default 60 s) applies end-to-end.

​

The context

• session_id / tenant_id — always present; use for scoping and auditing.
• propagation_headers / parent_trace_id / parent_span_id / baggage — W3C trace context, present when the caller had an active trace. Forward propagation_headers verbatim to downstream HTTP services; use parent_trace_id / parent_span_id when creating custom spans. See Trace propagation.

handler: async ({ invoice_id }, { tenant_id, propagation_headers }) => {
  const res = await fetch(`https://billing.internal/${tenant_id}/invoices/${invoice_id}`, {
    headers: propagation_headers ?? {},
  });
  return { invoice: await res.json() };
}

​

Errors

if (!invoice) {
  throw new Error(`invoice_not_found: ${invoice_id}`);
}

​

Tags

agent.define_capability({
  name: 'issue_refund',
  tags: ['billing', 'destructive'],
  /* … */
});

​

Adding capabilities after start

​

See also

• Agent.define_capability
• CapabilityConfig
• Calling other agents — what the other side of the wire looks like.