enterprise_ai.agent.clients

Source: sdks/python/src/enterprise_ai/agent/clients.py. Back to the Python SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Class AgentsClient

/v1/agents.

Resource

AgentsClient.create

create(manifest: dict[str, Any]) -> Any

Register an agent or a version. Applies an Agent manifest: creates the agent, or adds a version to an existing one and makes it current. The manifest is validated against the v1 contract (422 invalid_manifest); risk level unacceptable is refused (422 agent_risk_unacceptable); the same version with other content is refused (409 version_immutable). apply_status in the answer is created, version_added or unchanged. Needs tenant_admin, developer or application_owner; the caller becomes ReBAC owner. Audited as agent.apply.

Route: /v1/agents (POST).

Name	Type	Default	Required	Description
manifest	dict[str, Any]		yes	Agent Manifest sent as the request body.

Returns: Any. Decoded JSON answer of the operation "Register an agent or a version".

Raises: the typed errors of the transport (Errors).

AgentsClient.delete

delete(agent_id: str) -> Any

Delete an agent. Deletes the agent and its versions. Needs the role tenant_admin and the ReBAC relation owner on the agent. Refused with 409 agent_has_active_runs while a run of the agent is still active (pending, running, waiting or suspended); 404 agent_not_found for an unknown agent. Audited as agent.delete.

Route: /v1/agents/{agent_id} (DELETE).

Name	Type	Default	Required	Description
agent_id	str		yes	Identifier (UUID) or name of the agent.

Returns: Any. Decoded JSON answer of the operation "Delete an agent".

Raises: the typed errors of the transport (Errors).

AgentsClient.get

get(agent_id: str) -> Any

Get an agent. Returns the agent, the manifest of its current version and runs, the number of its runs per state. Needs the ReBAC relation viewer on the agent. 404 agent_not_found.

Route: /v1/agents/{agent_id} (GET).

Name	Type	Default	Required	Description
agent_id	str		yes	Identifier (UUID) or name of the agent.

Returns: Any. Decoded JSON answer of the operation "Get an agent".

Raises: the typed errors of the transport (Errors).

AgentsClient.kill

kill(agent_id: str, reason: str | None = None) -> Any

Kill an agent. Kill switch: every active run of the agent is cancelled with the error killed and the agent status becomes killed for good (it can never be resumed). Needs tenant_admin or security_officer. 409 agent_killed if already killed. The answer lists affected_runs. Audited as agent.kill.

Route: /v1/agents/{agent_id}/kill (POST).

Name	Type	Default	Required	Description
agent_id	str		yes	Identifier (UUID) or name of the agent.
reason	str | None	None	no	Why the action is taken. Written to the audit trail with the actor and the time.

Returns: Any. Decoded JSON answer of the operation "Kill an agent".

Raises: the typed errors of the transport (Errors).

AgentsClient.list

list(**page: Any) -> Any

List the agents. Agents of the tenant, in name order, paginated with cursor. Any tenant principal may call it.

Route: /v1/agents (GET).

Name	Type	Default	Required	Description
**page	Any		no	Pagination options: limit (maximum number of agents per page) and cursor (cursor of the page to read).

Returns: Any. Decoded JSON answer of the operation "List the agents".

Raises: the typed errors of the transport (Errors).

AgentsClient.resume

resume(agent_id: str) -> Any

Request the resumption of an agent. Opens a promotion approval to bring a suspended agent back to active and answers 202 with approval_id and status: pending_approval; approvers are tenant_admin or security_officer. Once approved, the runs suspended by the agent suspension resume. Needs tenant_admin or security_officer. Refused with 409 agent_killed, or 409 kill_switch_active while a SOC containment holds the agent (lifted only through POST /v1/soc/recoveries).

Route: /v1/agents/{agent_id}/resume (POST).

Name	Type	Default	Required	Description
agent_id	str		yes	Identifier (UUID) or name of the agent.

Returns: Any. Decoded JSON answer of the operation "Request the resumption of an agent".

Raises: the typed errors of the transport (Errors).

AgentsClient.run

run(agent_id: str, task: object = None, session_id: str | None = None, budgets: dict[str, Any] | None = None, start: bool | None = None, idempotency_key: str | None = None, **extra: Any) -> Any

Start a run of an agent. Creates a run and returns its Execution Contract (201). Needs tenant_admin, developer or agent, the scope agents:run and the ReBAC relation can_invoke. Steps: 1. The agent must be active (else 409 agent_not_active, audited as a denial). 2. The policy agent.run is evaluated with the agent risk, owner, purpose and the data_classification of the task (403 policy_denied). 3. The budget is the manifest budget, tightened by budgets (a request can never loosen it; 422 invalid_budget). 4. The delegation and workload identity are attached, the run is created in pending (or running with start=true) and audited as run.create. A repeated Idempotency-Key returns the first run; the same key for another agent answers 409 idempotency_conflict. An unknown session_id answers 404 session_not_found.

Route: /v1/agents/{agent_id}/runs (POST).

Name	Type	Default	Required	Description
agent_id	str		yes	Identifier (UUID) or name of the agent.
task	object	None	no	Task of the run: task_id, objective, input are kept; data_classification is used by the policy check.
session_id	str | None	None	no	Session (UUID) the run belongs to.
budgets	dict[str, Any] | None	None	no	Budget limits (for example max tokens, max_cost with amount and currency). They can only tighten the agent manifest budget; the currency must match.
start	bool | None	None	no	When true, the run starts in running. Default false (pending until the first step).
idempotency_key	str | None	None	no	Idempotency-Key header: a retry with the same key replays the first answer.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Start a run of an agent".

Raises: the typed errors of the transport (Errors).

AgentsClient.suspend

suspend(agent_id: str, reason: str | None = None) -> Any

Suspend an agent. Kill switch, reversible: the agent status becomes suspended, its active runs move to suspended and new runs are refused. Needs tenant_admin or security_officer. 409 agent_killed for a killed agent. The answer lists affected_runs. Audited as agent.suspend.

Route: /v1/agents/{agent_id}/suspend (POST).

Name	Type	Default	Required	Description
agent_id	str		yes	Identifier (UUID) or name of the agent.
reason	str | None	None	no	Why the action is taken. Written to the audit trail with the actor and the time.

Returns: Any. Decoded JSON answer of the operation "Suspend an agent".

Raises: the typed errors of the transport (Errors).

AgentsClient.update

update(agent_id: str, **changes: Any) -> Any

Update an agent. Changes the registry fields of the agent (owner, risk level, description, labels) without creating a version. Needs tenant_admin, developer or application_owner and the ReBAC relation editor. Invalid values answer 400 invalid_request. Audited as agent.update with the changed field names.

Route: /v1/agents/{agent_id} (PATCH).

Name	Type	Default	Required	Description
agent_id	str		yes	Identifier (UUID) or name of the agent.
**changes	Any		no	Fields of the agent to change, sent as the PATCH body.

Returns: Any. Decoded JSON answer of the operation "Update an agent".

Raises: the typed errors of the transport (Errors).

AgentsClient.versions

versions(agent_id: str) -> Any

List the versions of an agent. Every registered version of the agent, newest first, with its manifest, digest, author and current (true for the version in use). Needs the ReBAC relation viewer. One page only.

Route: /v1/agents/{agent_id}/versions (GET).

Name	Type	Default	Required	Description
agent_id	str		yes	Identifier (UUID) or name of the agent.

Returns: Any. Decoded JSON answer of the operation "List the versions of an agent".

Raises: the typed errors of the transport (Errors).

Class RunsClient

/v1/runs, /v1/checkpoints, /v1/heartbeats.

Resource

RunsClient.add_step

add_step(run_id: str, step: dict[str, Any]) -> Any

Report a step of a run. Records one step reported by the runtime and returns the decision of the Loop Controller: run_state, next_kind, retry, backoff_seconds, error, approval_id and the budgets. Needs tenant_admin, developer or agent. Steps: 1. The Kill Switch Registry and, for a sensitive step, the delegation chain, session and policy are checked. 2. A pending run moves to running; any other state than running answers 409 run_not_running. 3. Usage and cost are added to the budget consumption (cost in the run currency, else 400 invalid_request). 4. A step matching autonomy.human_approval_for without approval_id stays pending, an approval is opened and the run moves to waiting_approval; a step of kind approval with state pending opens an approval with quorum. 5. Budgets, max steps and retries decide the next state (failed or timed_out when exceeded).

Route: /v1/runs/{run_id}/steps (POST).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the run.
step	dict[str, Any]		yes	Resolution of the metric series in seconds, 10 to 86400, default 60.

Returns: Any. Decoded JSON answer of the operation "Report a step of a run".

Raises: the typed errors of the transport (Errors).

RunsClient.cancel

cancel(run_id: str, reason: str | None = None) -> Any

Cancel a run. Moves the run to cancelled with the error cancelled; its active sub-agent runs are cancelled too. Needs tenant_admin, developer, agent or security_officer. A run already terminal answers 409 invalid_transition. Audited as run.transition.

Route: /v1/runs/{run_id}/cancel (POST).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the run.
reason	str | None	None	no	Why the action is taken. Written to the audit trail with the actor and the time.

Returns: Any. Decoded JSON answer of the operation "Cancel a run".

Raises: the typed errors of the transport (Errors).

RunsClient.cancel_subagent

cancel_subagent(subagent_run_id: str, reason: str | None = None) -> Any

Cancel a run. Moves the run to cancelled with the error cancelled; its active sub-agent runs are cancelled too. Needs tenant_admin, developer, agent or security_officer. A run already terminal answers 409 invalid_transition. Audited as run.transition.

Route: /v1/runs/{run_id}/cancel (POST).

Name	Type	Default	Required	Description
subagent_run_id	str		yes	Identifier (UUID) of the run.
reason	str | None	None	no	Why the action is taken. Written to the audit trail with the actor and the time.

Returns: Any. Decoded JSON answer of the operation "Cancel a run".

Raises: the typed errors of the transport (Errors).

RunsClient.checkpoint

checkpoint(run_id: str, state: dict[str, Any], label: str | None = None, **extra: Any) -> Any

Save a checkpoint. Saves a state of the run with the next sequence number and the current step sequence, so the run can later resume from it. Needs tenant_admin, developer or agent. Refused with 409 run_finished on a run succeeded or cancelled. Emits checkpoint.created; audited as run.checkpoint.

Route: /v1/runs/{run_id}/checkpoints (POST).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the run.
state	dict[str, Any]		yes	State to save, any JSON value. Default: empty object.
label	str | None	None	no	Label of the checkpoint (up to 200 characters).
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Save a checkpoint".

Raises: the typed errors of the transport (Errors).

RunsClient.checkpoints

checkpoints(run_id: str) -> Any

List the checkpoints of a run. Checkpoints of the run in sequence order. One page only. 404 run_not_found.

Route: /v1/runs/{run_id}/checkpoints (GET).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the run.

Returns: Any. Decoded JSON answer of the operation "List the checkpoints of a run".

Raises: the typed errors of the transport (Errors).

RunsClient.delegate

delegate(run_id: str, agent: str, task: object, budgets: dict[str, Any] | None = None) -> Any

Spawn a sub-agent run. Starts a child run from a pending or running parent (else 409 run_not_running) and returns its Execution Contract. Needs tenant_admin, developer or agent and the scope agents:run. Checks, in order: the Kill Switch Registry; the depth against autonomy.max_depth (default 1, 409 subagent_depth_exceeded); the number of children against autonomy.max_subagents (default 3, 409 subagent_count_exceeded); the child agent against the subagents list of the parent manifest (403 subagent_not_allowed); the parent delegation. The child budget cannot exceed what the parent has left, the child joins the parent session, and a running parent records a subagent step.

Route: /v1/runs/{run_id}/subagents (POST).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the parent run.
agent	str		yes	Child agent, name or agent:<name>. Default: the agent of the parent run.
task	object		yes	Task of the child run (task_id, objective, input).
budgets	dict[str, Any] | None	None	no	Budget limits of the child, capped by what the parent has left.

Returns: Any. Decoded JSON answer of the operation "Spawn a sub-agent run".

Raises: the typed errors of the transport (Errors).

RunsClient.events

events(run_id: str, last_event_id: str | None = None) -> Any

Stream the events of a run. Server-Sent Events stream (text/event-stream) of the run events: run.created, run.state, step.recorded, checkpoint.created, subagent.spawned. Each message carries id, event and data (type, data, at). Steps: 1. The events already recorded after Last-Event-ID are sent. 2. Without follow the stream ends at once; with follow=true it polls every second. 3. The stream ends with an end event carrying the run state when the run is terminal, when timeout has elapsed or when the client disconnects. 404 run_not_found.

Route: /v1/runs/{run_id}/events (GET).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the run.
last_event_id	str | None	None	no	Identifier of the last event already received, sent as the Last-Event-ID header so the stream resumes after it.

Returns: Any. Decoded JSON answer of the operation "Stream the events of a run".

Raises: the typed errors of the transport (Errors).

RunsClient.get

get(run_id: str) -> Any

Get a run. Returns the Execution Contract v1 of the run: agent and version, task, state, steps, budget limits and consumption, errors, retry policy, resume information and trace. 404 run_not_found.

Route: /v1/runs/{run_id} (GET).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the run.

Returns: Any. Decoded JSON answer of the operation "Get a run".

Raises: the typed errors of the transport (Errors).

RunsClient.get_checkpoint

get_checkpoint(checkpoint_id: str) -> Any

Get a checkpoint. Returns one checkpoint: run, sequence number, step sequence at save time, label and saved state. 404 checkpoint_not_found.

Route: /v1/checkpoints/{checkpoint_id} (GET).

Name	Type	Default	Required	Description
checkpoint_id	str		yes	Identifier (UUID) of the checkpoint.

Returns: Any. Decoded JSON answer of the operation "Get a checkpoint".

Raises: the typed errors of the transport (Errors).

RunsClient.heartbeat

heartbeat(run_id: str, step: Any = None, message: str | None = None, progress: Any = None, worker: str | None = None, **extra: Any) -> Any

Send a run heartbeat. Records that the runtime is alive and tells it whether to go on: action is continue, or stop with a reason (run_cancelled, run_terminal, run_suspended, agent_killed, agent_suspended). The answer also gives stale_after_seconds. A terminal run is not updated. Needs tenant_admin, developer or agent. Audited only for the first heartbeat of a run and when the runtime is told to stop.

Route: /v1/runs/{run_id}/heartbeat (POST).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the run.
step	Any	None	no	Resolution of the metric series in seconds, 10 to 86400, default 60.
message	str | None	None	no	Status message (up to 2000 characters).
progress	Any	None	no	Progress: a number (for example a fraction from 0 to 1) or an object of the runtime choice.
worker	str | None	None	no	Worker running the run (up to 200 characters). Default: the calling principal.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Send a run heartbeat".

Raises: the typed errors of the transport (Errors).

RunsClient.list

list(state: str | None = None, agent_id: str | None = None, session_id: str | None = None, parent_run_id: str | None = None, **page: Any) -> Any

List the runs. Runs of the tenant, newest first, paginated with cursor. Filters: agent_id (id or name; agent is an alias), state, session_id, parent_run_id. An unknown state or a malformed UUID answers 400 invalid_request.

Route: /v1/runs (GET).

Name	Type	Default	Required	Description
state	str | None	None	no	Only the runs in this state: pending, running, waiting_approval, waiting_input, suspended, succeeded, failed, cancelled or timed_out.
agent_id	str | None	None	no	Only the runs of this agent (UUID or name).
session_id	str | None	None	no	Only the runs of this session (UUID).
parent_run_id	str | None	None	no	Only the sub-agent runs started by this parent run (UUID).
**page	Any		no	Pagination options: limit (maximum number of runs per page) and cursor (cursor of the page to read).

Returns: Any. Decoded JSON answer of the operation "List the runs".

Raises: the typed errors of the transport (Errors).

RunsClient.replay

replay(run_id: str) -> Any

Replay a run. Returns the full history of a run for review: its Execution Contract, steps, checkpoints, the audit events that name it and a single timeline sorted by time (run events and audit events). Needs tenant_admin, developer, agent, auditor or security_officer. Read only: nothing is re-executed.

Route: /v1/runs/{run_id}/replay (GET).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the run.

Returns: Any. Decoded JSON answer of the operation "Replay a run".

Raises: the typed errors of the transport (Errors).

RunsClient.resume

resume(run_id: str, checkpoint_id: str | None = None) -> Any

Resume a run. Moves a suspended, failed, timed_out or waiting_input run back to running (else 409 invalid_transition). Needs tenant_admin, developer or agent; the agent must be active (409 agent_not_active). Strategies: 1. from_last_checkpoint (default, except for waiting_input): resume from checkpoint_id or the last checkpoint (409 no_checkpoint if none). 2. restart_step (default for waiting_input): replay the current step. 3. restart_run: start over with the budget consumption reset. A run that failed on budget_exceeded, max_steps_exceeded, killed or approval_rejected can only use restart_run (409 run_not_resumable). Returns the run and the checkpoint used.

Route: /v1/runs/{run_id}/resume (POST).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the run.
checkpoint_id	str | None	None	no	Identifier (UUID) of the checkpoint.

Returns: Any. Decoded JSON answer of the operation "Resume a run".

Raises: the typed errors of the transport (Errors).

RunsClient.spawn_subagent

spawn_subagent(run_id: str, agent: str, task: object = None, **extra: Any) -> Any

Spawn a sub-agent run. Starts a child run from a pending or running parent (else 409 run_not_running) and returns its Execution Contract. Needs tenant_admin, developer or agent and the scope agents:run. Checks, in order: the Kill Switch Registry; the depth against autonomy.max_depth (default 1, 409 subagent_depth_exceeded); the number of children against autonomy.max_subagents (default 3, 409 subagent_count_exceeded); the child agent against the subagents list of the parent manifest (403 subagent_not_allowed); the parent delegation. The child budget cannot exceed what the parent has left, the child joins the parent session, and a running parent records a subagent step.

Route: /v1/runs/{run_id}/subagents (POST).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the parent run.
agent	str		yes	Child agent, name or agent:<name>. Default: the agent of the parent run.
task	object	None	no	Task of the child run (task_id, objective, input).
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Spawn a sub-agent run".

Raises: the typed errors of the transport (Errors).

RunsClient.stale_heartbeats

stale_heartbeats(**params: Any) -> Any

List run heartbeats. Liveness of the runs expected to send heartbeats (running and waiting_input). By default only the stale ones (no heartbeat within the threshold) are returned, with active, stale_count and stale_after_seconds. With format=prometheus the answer is Prometheus exposition text (eai_runs_total, eai_runs_active, eai_runs_stale, eai_heartbeat_stale_threshold_seconds).

Route: /v1/heartbeats (GET).

Name	Type	Default	Required	Description
**params	Any		no	Extra fields merged into the request.

Returns: Any. Decoded JSON answer of the operation "List run heartbeats".

Raises: the typed errors of the transport (Errors).

RunsClient.steps

steps(run_id: str) -> Any

List the steps of a run. Steps of the run in order, each with seq, kind, state, attempt, tokens, cost and error when present. One page only. 404 run_not_found.

Route: /v1/runs/{run_id}/steps (GET).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the run.

Returns: Any. Decoded JSON answer of the operation "List the steps of a run".

Raises: the typed errors of the transport (Errors).

RunsClient.subagents

subagents(run_id: str) -> Any

List the sub-agent runs. Summaries of the child runs started by this run, oldest first. One page only. 404 run_not_found.

Route: /v1/runs/{run_id}/subagents (GET).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the parent run.

Returns: Any. Decoded JSON answer of the operation "List the sub-agent runs".

Raises: the typed errors of the transport (Errors).

Class SessionsClient

/v1/sessions and their messages.

Resource

SessionsClient.create

create(agent_id: str | None = None, **extra: Any) -> Any

Open a session. Opens a conversation session, owned by user_id or by the caller. Opening a session for another user needs tenant_admin or agent (403 forbidden). Needs tenant_admin, developer or agent. 404 agent_not_found for an unknown agent_id. Audited as session.create.

Route: /v1/sessions (POST).

Name	Type	Default	Required	Description
agent_id	str | None	None	no	Agent of the conversation (UUID or name).
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Open a session".

Raises: the typed errors of the transport (Errors).

SessionsClient.delete

delete(session_id: str) -> Any

Delete a session. Deletes the session and its messages. Needs tenant_admin, developer or agent, and the caller must see the session (its owner, or tenant_admin, auditor, security_officer, agent); otherwise 404 session_not_found. Audited as session.delete.

Route: /v1/sessions/{session_id} (DELETE).

Name	Type	Default	Required	Description
session_id	str		yes	Identifier (UUID) of the session.

Returns: Any. Decoded JSON answer of the operation "Delete a session".

Raises: the typed errors of the transport (Errors).

SessionsClient.get

get(session_id: str) -> Any

Get a session. Returns one session. Visible to its owner, to tenant_admin, auditor, security_officer and to the agent role; otherwise 404 session_not_found.

Route: /v1/sessions/{session_id} (GET).

Name	Type	Default	Required	Description
session_id	str		yes	Identifier (UUID) of the session.

Returns: Any. Decoded JSON answer of the operation "Get a session".

Raises: the typed errors of the transport (Errors).

SessionsClient.list

list(**page: Any) -> Any

List the sessions. Sessions, newest first, paginated with cursor. A caller sees its own sessions; tenant_admin, auditor and security_officer see every session of the tenant.

Route: /v1/sessions (GET).

Name	Type	Default	Required	Description
**page	Any		no	Pagination options: limit (maximum number of sessions per page) and cursor (cursor of the page to read).

Returns: Any. Decoded JSON answer of the operation "List the sessions".

Raises: the typed errors of the transport (Errors).

SessionsClient.messages

messages(session_id: str, **page: Any) -> Any

List the messages of a session. Messages in order, paginated with cursor. after (message id or timestamp) lets a runtime poll the new messages only; an unknown message id or a malformed timestamp answers 400 invalid_request.

Route: /v1/sessions/{session_id}/messages (GET).

Name	Type	Default	Required	Description
session_id	str		yes	Identifier (UUID) of the session.
**page	Any		no	Pagination options: limit (maximum number of messages per page) and cursor (cursor of the page to read).

Returns: Any. Decoded JSON answer of the operation "List the messages of a session".

Raises: the typed errors of the transport (Errors).

SessionsClient.post_message

post_message(session_id: str, content: str, role: str = 'user', **extra: Any) -> Any

Add a message to a session. Appends a message with the next sequence number. The session must be open and not expired (409 session_closed). Needs tenant_admin, developer or agent. The audit event session.message.add keeps the role and the length only, never the content.

Route: /v1/sessions/{session_id}/messages (POST).

Name	Type	Default	Required	Description
session_id	str		yes	Identifier (UUID) of the session.
content	str		yes	Text of the message (1 to 200000 characters).
role	str	'user'	no	Author role: user (default), assistant, system or tool.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Add a message to a session".

Raises: the typed errors of the transport (Errors).

Class A2AClient

Agent to agent messaging with a versioned envelope.

Resource

A2AClient.inbox

inbox(recipient: str, unread: bool | None = None, **page: Any) -> Any

Read an A2A inbox. Returns the A2A messages addressed to recipient, oldest first, each with verified (the HMAC-SHA256 signature of the envelope matches the tenant key). Reading marks the returned messages as read. One page only (next_cursor is always null).

Route: /v1/a2a/inbox (GET).

Name	Type	Default	Required	Description
recipient	str		yes	Party whose inbox is read: agent:<name> or run:<id> (at least 3 characters).
unread	bool | None	None	no	When true, only the messages not read yet. Default false.
**page	Any		no	Pagination options: limit (maximum number of messages per page) and cursor (cursor of the page to read).

Returns: Any. Decoded JSON answer of the operation "Read an A2A inbox".

Raises: the typed errors of the transport (Errors).

A2AClient.send

send(to: str, payload: dict[str, Any] | None = None, type: str = 'request', sender: str | None = None, conversation_id: str | None = None, in_reply_to: str | None = None, **extra: Any) -> Any

Send an A2A message. Sends a signed agent to agent message (envelope a2a.v1, HMAC-SHA256 signature per tenant). Needs tenant_admin, developer or agent. Steps: 1. to and from are resolved: agent:<name> or run:<id> (400 invalid_request otherwise). Without from, the sender is the calling principal. 2. A run: sender must be a run created by the caller (or the caller is tenant_admin, else 403 forbidden) and not finished (409 run_finished). 3. The policy agent.a2a.send is evaluated and the payload is screened as untrusted content; a prompt injection is refused with prompt_injection_blocked after the security event is recorded. 4. The envelope is stored in the recipient inbox and audited as a2a.send.

Route: /v1/a2a/messages (POST).

Name	Type	Default	Required	Description
to	str		yes	Recipient: agent:<name> or run:<id> (3 to 300 characters).
payload	dict[str, Any] | None	None	no	Content of the message, any JSON value. Screened for prompt injection before delivery.
type	str	'request'	no	Message type: request, response or event.
sender	str | None	None	no	Identifier of the sending agent, sent as the from field of the envelope; omitted when empty.
conversation_id	str | None	None	no	Conversation the message belongs to (up to 200 characters). A new one is generated when omitted.
in_reply_to	str | None	None	no	Identifier of the message this one answers.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Send an A2A message".

Raises: ValueError, the typed errors of the transport (Errors).