> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Handoffs & A2A

> Python API reference for Handoffs & A2A.

Move a call between agents and let agents talk to each other: handoff helpers for
transferring control, and agent-to-agent (A2A) messaging primitives.

## agent\_switch

```python theme={null}
def agent_switch(to: str, *, from_: str = '', reason: str = '', inherit_context: bool = True, extra: dict | None = None) -> dict
```

Build a handoff instruction that transfers control to another agent.

Produces a dictionary keyed by the agent-switch marker, suitable for
signalling the runtime that the active agent should change.

<ParamField path="to" type="str" required>
  Name of the target agent to switch to.
</ParamField>

<ParamField path="from_" type="str" default="">
  Name of the agent initiating the switch. Omitted from the payload when empty.
</ParamField>

<ParamField path="reason" type="str" default="">
  Optional human-readable explanation for the switch. Omitted from the payload when empty.
</ParamField>

<ParamField path="inherit_context" type="bool" default="True">
  Whether the target agent should inherit the current conversation context. Defaults to `True`.
</ParamField>

<ParamField path="extra" type="dict | None">
  Additional top-level keys merged into the returned dictionary.
</ParamField>

<ResponseField name="returns" type="dict">
  A dictionary containing the agent-switch payload, with any `extra` keys merged in at the top level.
</ResponseField>

***

## AGENT\_SWITCH\_KEY

```python theme={null}
AGENT_SWITCH_KEY = '__agent_switch__'
```

***

## AgentCard

Descriptor advertising an agent's identity and capabilities.

### Fields

<ParamField path="agent_id" type="str" default="">
  Unique identifier for the agent.
</ParamField>

<ParamField path="name" type="str" default="">
  Human-readable name of the agent.
</ParamField>

<ParamField path="description" type="str" default="">
  Description of what the agent does.
</ParamField>

<ParamField path="capabilities" type="List[str]" default="…">
  List of capabilities the agent provides.
</ParamField>

<ParamField path="metadata" type="Dict[str, Any]" default="…">
  Arbitrary additional metadata about the agent.
</ParamField>

***

## A2AMessage

A message exchanged between two agents.

### Fields

<ParamField path="source_agent_id" type="str" default="">
  Identifier of the sending agent.
</ParamField>

<ParamField path="target_agent_id" type="str" default="">
  Identifier of the receiving agent.
</ParamField>

<ParamField path="message_type" type="str" default="text">
  Type discriminator for the message (e.g. `'text'`).
</ParamField>

<ParamField path="payload" type="Dict[str, Any]" default="…">
  Message contents keyed by field name.
</ParamField>