Skip to navigation
Command reference

agents Commands

View as Markdown

Manage agents

Output formatting flags (--json, --jq, and --template) are documented once in Output Formatting and are omitted from the tables below.

bctrl agents a2a card

The Agent2Agent (A2A v1.0) card of this Agent: its JSON-RPC interface, capabilities and bearer API-key security.

bctrl agents a2a card <agentId> [flags]
FlagDescription
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)

bctrl agents a2a rpc

A2A v1.0 JSON-RPC: SendMessage starts or continues a Task (blocking unless configuration.returnImmediately), GetTask, ListTasks and CancelTask read and cancel this Agent’s Tasks. Send the A2A-Version: 1.0 header. Errors are JSON-RPC errors with HTTP 200.

bctrl agents a2a rpc <agentId> [flags]
FlagDescription
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)
--idempotency-key <key>Retry key for this operation
--body <json>Request body: inline JSON, @file, or - for stdin

bctrl agents create

Create an Agent and its first immutable, promoted version in a Space.

bctrl agents create [flags]
FlagDescription
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)
--idempotency-key <key>Retry key for this operation
--body <json>Request body: inline JSON, @file, or - for stdin

bctrl agents delete

Archive an Agent definition. Existing Tasks and immutable version history remain available.

bctrl agents delete <agentId> [flags]
FlagDescription
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)
--idempotency-key <key>Retry key for this operation
--yesConfirm this destructive operation

bctrl agents get

Read an Agent by ID or scoped name, including its promoted version and latest draft number.

bctrl agents get <agentId> [flags]
FlagDescription
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)

bctrl agents list

List Agent definitions visible in the selected Space or tenant, with their promoted immutable version.

bctrl agents list [flags]
FlagDescription
--query <json>Query object: inline JSON, @file, or - for stdin
--params <json>Alias for —query
--cursor <value>Query parameter cursor
--order <value>Query parameter order
--limit <value>Query parameter limit
--name <value>Query parameter name
--space-id <value>Query parameter spaceId
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)

bctrl agents update

Append an immutable Agent version. Tasks keep their selected version and the promoted version changes only on promotion.

bctrl agents update <agentId> [flags]
FlagDescription
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)
--idempotency-key <key>Retry key for this operation
--body <json>Request body: inline JSON, @file, or - for stdin

bctrl agents versions get

Read the immutable definition of one numbered Agent version.

bctrl agents versions get <agentId> <version> [flags]
FlagDescription
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)

bctrl agents versions list

List immutable versions of an Agent in creation order.

bctrl agents versions list <agentId> [flags]
FlagDescription
--query <json>Query object: inline JSON, @file, or - for stdin
--params <json>Alias for —query
--cursor <value>Query parameter cursor
--order <value>Query parameter order
--limit <value>Query parameter limit
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)

bctrl agents versions promote

Select an immutable version for future Tasks. When approval is required, a person must promote it or answer the stored Task approval request.

bctrl agents versions promote <agentId> <version> [flags]
FlagDescription
--headers <json>API headers: inline JSON, @file, or - for stdin
--api-version <date>Dated API contract (default: 2026-10-03)
--space <id-or-name>Select an authorized Space (BCTRL-Space)
--subaccount-id <id>Effective subaccount context (BCTRL-Subaccount-Id)
--idempotency-key <key>Retry key for this operation
--body <json>Request body: inline JSON, @file, or - for stdin