a2a

Extracts A2A protocol metadata from JSON-RPC request bodies and promotes method, family, task ID, streaming detection, and version to request headers, filter results, and durable metadata for routing.

Praxis AI documentation version

On this page

Configuration Notes

When task_routing.enabled is true, the filter captures task and context ownership from backend responses and uses it to route follow-up requests. Task-owner routing sends GetTask, CancelTask, SubscribeToTask, and push-notification config methods back to the backend that created the task. Context-owner routing sends ListTasks, SendMessage, and SendStreamingMessage requests carrying a known contextId back to the backend that owns the context. Task-ID routes take precedence over context-ID routes. Context routes always use ttl_seconds; a completed task does not evict the context route.

Configuration

Field	Type	Required	Description
`headers`	A2aHeaders	no	Header names for A2A metadata promotion. Must not be hop-by-hop, framing, Host, credential, API-key, or other internal `x-praxis-` names. Dedicated `x-praxis-a2a-` defaults remain allowed.
`headers.context_id`	string	no	Header name for the extracted context ID (e.g. `x-praxis-a2a-context-id`).
`headers.family`	string	no	Header name for the A2A family (e.g. `x-praxis-a2a-family`).
`headers.kind`	string	no	Header name for the JSON-RPC kind (e.g. `x-praxis-a2a-kind`).
`headers.method`	string	no	Header name for the canonical A2A method (e.g. `x-praxis-a2a-method`).
`headers.streaming`	string	no	Header name for streaming detection (e.g. `x-praxis-a2a-streaming`).
`headers.task_id`	string	no	Header name for the extracted task ID (e.g. `x-praxis-a2a-task-id`).
`headers.version`	string	no	Header name for A2A version (e.g. `x-praxis-a2a-version`).
`max_body_bytes`	integer	no	Maximum body size in bytes for `StreamBuffer`.
`method_aliases`	object<string, string>	no	Method aliases for compatibility (slash-delimited → `PascalCase`).
`on_invalid`	`continue` \| `reject` \| `error`	no	Invalid input handling behavior.
`task_routing`	TaskRoutingConfig	no	Task-ownership routing configuration.
`task_routing.enabled`	bool	no	Whether task routing is enabled.
`task_routing.max_response_body_bytes`	integer	no	Maximum response body bytes to buffer for task route capture.
`task_routing.on_lookup_miss`	`continue`	no	Behavior when a task route lookup misses.
`task_routing.route_cluster_header`	string	no	Internal header name injected on task or context route hit.
`task_routing.store`	`local`	no	Storage backend for task routes.
`task_routing.terminal_ttl_seconds`	integer	no	TTL in seconds for terminal task routes (0 = remove immediately). Must be at most 2,592,000 (30 days).
`task_routing.ttl_seconds`	integer	no	TTL in seconds for non-terminal task routes. Must be greater than 0 and at most 2,592,000 (30 days).

Examples

Example 1

filter: a2a

Example 2

filter: a2a
max_body_bytes: 65536
on_invalid: reject
method_aliases:
  message/send: SendMessage
  message/stream: SendStreamingMessage
  tasks/get: GetTask
  tasks/cancel: CancelTask
headers:
  method: x-praxis-a2a-method
  family: x-praxis-a2a-family
  context_id: x-praxis-a2a-context-id
  task_id: x-praxis-a2a-task-id
  kind: x-praxis-a2a-kind
  streaming: x-praxis-a2a-streaming
  version: x-praxis-a2a-version
task_routing:
  enabled: true
  store: local
  route_cluster_header: x-praxis-a2a-route-cluster
  ttl_seconds: 3600
  terminal_ttl_seconds: 300
  max_response_body_bytes: 65536

a2a