resources/agents.ts

Source: sdks/typescript/packages/sdk/src/resources/agents.ts. Back to the TypeScript 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.

Interface RunCreate

Body of POST /v1/agents/{id}/runs.

Doc

Fields:

Name	Type	Required	Description
task	{ objective?: string; input?: unknown; task_id?: string } & Doc	no	Task given to the agent: objective, input and task_id are kept on the run.
session_id	string	no	Session the run belongs to.
budgets	Doc	no	Budgets of the run.
retry_policy	Doc	no	Retry policy: max_attempts (1 or more, default 3) and backoff_seconds (0 or more, default 2).
start	boolean	no	Starts the run immediately (default true).

Class AgentsResource

Agents. Registry of the tenant's agents and the server side execution of their runs: steps, budgets, checkpoints, heartbeats, sub-agents, agent to agent (A2A) messages, conversation sessions, cron schedules, event triggers and sandbox executions.

Resource

AgentsResource.create

create(body: Doc, opts?: CallOptions)

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
body	Doc		yes	Agent manifest (kind: Agent, metadata with name, version and owner, spec).
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

AgentsResource.delete

delete(id: string, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) or name of the agent.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

AgentsResource.get

get(id: string, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) or name of the agent.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

AgentsResource.iterate

iterate(params?: ListParams, opts?: CallOptions)

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
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

AgentsResource.kill

kill(id: string, body: { reason?: string } = {}, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) or name of the agent.
body	{ reason?: string }	{}	no	Optional reason, kept on the agent and in the audit trail.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

AgentsResource.list

list(params?: ListParams, opts?: CallOptions)

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
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

AgentsResource.resume

resume(id: string, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) or name of the agent.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

AgentsResource.run

run(id: string, body: RunCreate = {}, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) or name of the agent.
body	RunCreate	{}	no	Task of the run, optional session, budget, retry policy and delegation.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

AgentsResource.suspend

suspend(id: string, body: { reason?: string } = {}, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) or name of the agent.
body	{ reason?: string }	{}	no	Optional reason, kept on the agent and in the audit trail.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

AgentsResource.update

update(id: string, body: Doc, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) or name of the agent.
body	Doc		yes	Fields to change; the omitted ones are kept.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

AgentsResource.versions

versions(id: string, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) or name of the agent.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class RunsResource

Agents. Registry of the tenant's agents and the server side execution of their runs: steps, budgets, checkpoints, heartbeats, sub-agents, agent to agent (A2A) messages, conversation sessions, cron schedules, event triggers and sandbox executions.

Resource

RunsResource.addStep

addStep(id: string, body: Doc, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the run.
body	Doc		yes	The step: kind, state, usage, cost, error and run state hints.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

RunsResource.cancel

cancel(id: string, body: { reason?: string } = {}, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the run.
body	{ reason?: string }	{}	no	Optional reason of the cancellation.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

RunsResource.create

create(agentId: string, body: RunCreate = {}, opts?: CallOptions)

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
agentId	string		yes	Identifier (UUID) or name of the agent.
body	RunCreate	{}	no	Task of the run, optional session, budget, retry policy and delegation.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

RunsResource.get

get(id: string, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the run.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

RunsResource.iterate

iterate(params?: ListParams, opts?: CallOptions)

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
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

RunsResource.list

list(params?: ListParams, opts?: CallOptions)

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
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

RunsResource.replay

replay(id: string, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the run.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

RunsResource.resume

resume(id: string, body: { checkpoint_id?: string; strategy?: string } = {}, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the run.
body	{ checkpoint_id?: string; strategy?: string }	{}	no	Optional checkpoint and resume strategy.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

RunsResource.steps

steps(id: string, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the run.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class CheckpointsResource

Agents. Registry of the tenant's agents and the server side execution of their runs: steps, budgets, checkpoints, heartbeats, sub-agents, agent to agent (A2A) messages, conversation sessions, cron schedules, event triggers and sandbox executions.

Resource

CheckpointsResource.create

create(runId: string, body: Doc, opts?: CallOptions)

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
runId	string		yes	Identifier (UUID) of the run.
body	Doc		yes	State to save and optional label.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

CheckpointsResource.get

get(id: string, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the checkpoint.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

CheckpointsResource.list

list(runId: string, opts?: CallOptions)

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
runId	string		yes	Identifier (UUID) of the run.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Interface HeartbeatResponse

Shared heartbeat semantics: the runtime MUST stop when action is stop.

Doc

Fields:

Name	Type	Required	Description
run_id	string	yes	Id of the run the heartbeat was sent for.
state	string	yes	Current state of the run.
agent_status	"active" | "suspended" | "killed"	yes	Status of the agent: active, suspended or killed.
action	"continue" | "stop"	yes	continue or stop; the runtime must stop on stop.
reason	string | null	yes	Why the action is taken. Written to the audit trail with the actor and the time.

Class HeartbeatsResource

Agents. Registry of the tenant's agents and the server side execution of their runs: steps, budgets, checkpoints, heartbeats, sub-agents, agent to agent (A2A) messages, conversation sessions, cron schedules, event triggers and sandbox executions.

Resource

HeartbeatsResource.send

send(runId: string, body: { step?: string; progress?: Doc | number; message?: string; worker?: string } & Doc = {}, opts?: CallOptions)

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
runId	string		yes	Identifier (UUID) of the run.
body	{ step?: string; progress?: Doc | number; message?: string; worker?: string } & Doc	{}	no	Optional progress information.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

HeartbeatsResource.stale

stale(params?: ListParams, opts?: CallOptions)

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	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class SubagentsResource

Agents. Registry of the tenant's agents and the server side execution of their runs: steps, budgets, checkpoints, heartbeats, sub-agents, agent to agent (A2A) messages, conversation sessions, cron schedules, event triggers and sandbox executions.

Resource

SubagentsResource.cancel

cancel(subagentRunId: string, body: { reason?: string } = {}, opts?: CallOptions)

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
subagentRunId	string		yes	Identifier (UUID) of the run.
body	{ reason?: string }	{}	no	Optional reason of the cancellation.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SubagentsResource.delegate

delegate(runId: string, body: { agent: string; task: unknown; budgets?: Doc }, opts?: CallOptions)

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
runId	string		yes	Identifier (UUID) of the parent run.
body	{ agent: string; task: unknown; budgets?: Doc }		yes	Child agent, task and budget.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SubagentsResource.list

list(runId: string, opts?: CallOptions)

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
runId	string		yes	Identifier (UUID) of the parent run.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SubagentsResource.spawn

spawn(runId: string, body: Doc, opts?: CallOptions)

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
runId	string		yes	Identifier (UUID) of the parent run.
body	Doc		yes	Child agent, task and budget.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class A2AResource

Agents. Registry of the tenant's agents and the server side execution of their runs: steps, budgets, checkpoints, heartbeats, sub-agents, agent to agent (A2A) messages, conversation sessions, cron schedules, event triggers and sandbox executions.

Resource

A2AResource.inbox

inbox(params: { recipient: string; unread?: boolean; limit?: number }, opts?: CallOptions)

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
params	{ recipient: string; unread?: boolean; limit?: number }		yes	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

A2AResource.send

send(body: { to: string; type: "request" | "response" | "event"; from?: string; payload?: unknown; conversation_id?: string; in_reply_to?: string } & Doc, opts?: CallOptions)

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
body	{ to: string; type: "request" | "response" | "event"; from?: string; payload?: unknown; conversation_id?: string; in_reply_to?: string } & Doc		yes	Recipient, message type, payload and optional conversation threading.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class SessionsResource

Agents. Registry of the tenant's agents and the server side execution of their runs: steps, budgets, checkpoints, heartbeats, sub-agents, agent to agent (A2A) messages, conversation sessions, cron schedules, event triggers and sandbox executions.

Resource

SessionsResource.create

create(body: Doc = {}, opts?: CallOptions)

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
body	Doc	{}	no	Agent, owner, channel, title, metadata and lifetime of the session.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SessionsResource.delete

delete(id: string, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the session.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SessionsResource.get

get(id: string, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the session.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SessionsResource.list

list(params?: ListParams, opts?: CallOptions)

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
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SessionsResource.listMessages

listMessages(id: string, params?: ListParams, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the session.
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SessionsResource.sendMessage

sendMessage(id: string, body: { role?: string; content: unknown } & Doc, opts?: CallOptions)

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
id	string		yes	Identifier (UUID) of the session.
body	{ role?: string; content: unknown } & Doc		yes	Role, content and metadata of the message.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class SchedulesResource

Agents. Registry of the tenant's agents and the server side execution of their runs: steps, budgets, checkpoints, heartbeats, sub-agents, agent to agent (A2A) messages, conversation sessions, cron schedules, event triggers and sandbox executions.

Resource

SchedulesResource.create

create(body: { cron: string; agent_id: string; enabled?: boolean; timezone?: string; input?: unknown } & Doc, opts?: CallOptions)

Create a schedule. Schedules runs of an agent from a cron expression evaluated in a time zone; the first next_run_at is computed (422 invalid_cron). When Temporal is configured the schedule is created there (503 scheduler_unavailable on failure). Needs tenant_admin, developer or application_owner. 404 agent_not_found. Audited as schedule.create.

Route: /v1/schedules (POST).

Name	Type	Default	Required	Description
body	{ cron: string; agent_id: string; enabled?: boolean; timezone?: string; input?: unknown } & Doc		yes	Agent, cron expression, time zone, run input and enabled flag.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SchedulesResource.delete

delete(id: string, opts?: CallOptions)

Delete a schedule. Deletes the schedule; no new run is started by it. Needs tenant_admin, developer or application_owner. When the schedule is held by Temporal, it is deleted there too (503 scheduler_unavailable if Temporal cannot be reached). 404 schedule_not_found. Audited as schedule.delete.

Route: /v1/schedules/{schedule_id} (DELETE).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the schedule.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SchedulesResource.list

list(params?: ListParams, opts?: CallOptions)

List the schedules. Cron schedules of the tenant, oldest first, optionally for one agent. One page only.

Route: /v1/schedules (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SchedulesResource.update

update(id: string, body: Doc, opts?: CallOptions)

Update a schedule. Changes the cron expression, time zone, input or enabled flag. The next run time is computed again (422 invalid_cron for a bad expression or time zone) and the Temporal schedule is updated when Temporal holds it (503 scheduler_unavailable). Needs tenant_admin, developer or application_owner. Audited as schedule.update.

Route: /v1/schedules/{schedule_id} (PATCH).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the schedule.
body	Doc		yes	Fields to change; the omitted ones are kept.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class TriggersResource

Agents. Registry of the tenant's agents and the server side execution of their runs: steps, budgets, checkpoints, heartbeats, sub-agents, agent to agent (A2A) messages, conversation sessions, cron schedules, event triggers and sandbox executions.

Resource

TriggersResource.create

create(body: { subject: string; agent_id: string; filter?: string } & Doc, opts?: CallOptions)

Create a trigger. Starts a run of the agent for every published event whose subject matches (NATS wildcards * and > allowed) and whose payload passes the filter. Needs tenant_admin, developer or application_owner. 422 invalid_subject or invalid_filter; 404 agent_not_found. Audited as trigger.create.

Route: /v1/triggers (POST).

Name	Type	Default	Required	Description
body	{ subject: string; agent_id: string; filter?: string } & Doc		yes	Agent, subject and optional payload filter.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

TriggersResource.delete

delete(id: string, opts?: CallOptions)

Delete a trigger. Deletes the event trigger; matching events no longer start runs. Needs tenant_admin, developer or application_owner. 404 trigger_not_found. Audited as trigger.delete.

Route: /v1/triggers/{trigger_id} (DELETE).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the trigger.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

TriggersResource.list

list(params?: ListParams, opts?: CallOptions)

List the triggers. Event triggers of the tenant, oldest first: agent, subject and filter. One page only.

Route: /v1/triggers (GET).

Name	Type	Default	Required	Description
params	ListParams		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class EventsResource

Agents. Registry of the tenant's agents and the server side execution of their runs: steps, budgets, checkpoints, heartbeats, sub-agents, agent to agent (A2A) messages, conversation sessions, cron schedules, event triggers and sandbox executions.

Resource

EventsResource.publish

publish(body: { subject: string; payload?: unknown; headers?: Record<string, string> } & Doc, opts?: CallOptions)

Publish an event. Publishes an event (202): on NATS JetStream when configured, else in the platform outbox. The current W3C trace context is added to the headers. Every trigger whose subject and filter match starts a run of its agent (idempotent per event and trigger); the answer lists them in triggered, with skipped and an error code when a run could not start. Needs tenant_admin, developer or agent. 422 invalid_subject. Audited as event.publish.

Route: /v1/events/publish (POST).

Name	Type	Default	Required	Description
body	{ subject: string; payload?: unknown; headers?: Record<string, string> } & Doc		yes	Subject, payload and headers of the event.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

Class SandboxResource

Agents. Registry of the tenant's agents and the server side execution of their runs: steps, budgets, checkpoints, heartbeats, sub-agents, agent to agent (A2A) messages, conversation sessions, cron schedules, event triggers and sandbox executions.

Resource

SandboxResource.execute

execute(body: { image: string; command?: string[]; env?: Record<string, string>; profile?: "gvisor" | "kata" | "wasm" | "none"; limits?: Doc; run_id?: string } & Doc, opts?: CallOptions)

Run a command in a sandbox. Creates a sandbox execution: the image and command run as a Kubernetes Job with the runtime class of the profile (gVisor, Kata, Wasm) when Kubernetes is configured (status: submitted, or failed if the submission fails). Needs tenant_admin, developer or agent; the profile none needs tenant_admin (403). Invalid profile, image or limits answer 422 invalid_sandbox. The usage is metered and the request audited as sandbox.execute.

Route: /v1/sandbox/executions (POST).

Name	Type	Default	Required	Description
body	{ image: string; command?: string[]; env?: Record<string, string>; profile?: "gvisor" | "kata" | "wasm" | "none"; limits?: Doc; run_id?: string } & Doc		yes	Profile, image, command, environment and resource limits.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SandboxResource.get

get(id: string, opts?: CallOptions)

Get a sandbox execution. Returns the sandbox execution: profile, image, command, limits, generated Kubernetes Job spec, status, executor and result. 404 sandbox_execution_not_found.

Route: /v1/sandbox/executions/{execution_id} (GET).

Name	Type	Default	Required	Description
id	string		yes	Identifier (UUID) of the sandbox execution.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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