Run a session

One operation runs an agent: POST /sessions/{id} (see the API reference), albus sessions run in the CLI, sessions.run_session in Python, sessions.runSession in TypeScript. Everything on this page is that one call. Each call is an invocation: one prompt, one agent run, one assistant reply.

Session identity is yours to choose

You supply the session id. Albus creates the session on the first run and resumes it on every later one, so a session is created and continued by the same call.

albus sessions run support-1234 -p "customer says login fails" \
  --agent-name support-triage --model gemini-3.6-flash
albus sessions run support-1234 -p "what did they try already?" \
  --agent-name support-triage --model gemini-3.6-flash

Ids match ^[0-9a-zA-Z._:-]+$, 2–100 characters — use something meaningful from your own system (support-1234, pr-987, nightly:2026-08-11) so you can find the session again without storing a mapping. The response’s session.invocation_count tells you how many runs the session has had, and session.state is RUNNING, DONE, FAILED, or CANCELED.

A run loads up to the session’s most recent 1000 messages as history. Beyond that, older turns fall out. There is no memory beyond a session — see alpha limitations.

Waiting for the reply

A run is asynchronous underneath, with two ways to collect the result. Wait (long-poll). The request blocks until the assistant’s reply exists and returns it in messages. This is the CLI default, and wait=true in the API.

albus sessions run support-1234 -p "summarize" \
  --agent-name support-triage --model gemini-3.6-flash \
  --wait-timeout 120

--wait-timeout (wait_timeout) bounds the wait server-side. If it elapses first the request fails with 504 and a JSON body — the run is still going, and retrying the same idempotency key re-attaches to it. Omit the timeout and the request waits as long as your client stays connected. Don’t wait. Return as soon as the invocation is accepted, then poll.

albus sessions run support-1234 -p "summarize" \
  --agent-name support-triage --model gemini-3.6-flash --no-wait
albus sessions get support-1234

sessions get pages messages with --after/--limit; each message carries a monotonic cursor, so pass the last cursor you saw as after to fetch what is new.

Idempotency

Supply an idempotency key and the run becomes retry-safe: a network failure, a 504, or a lost response costs nothing.

albus sessions run support-1234 -p "summarize" \
  --agent-name support-triage --model gemini-3.6-flash \
  --idempotency-key "support-1234-summary-1"

Situation	Result
Same key, identical body	Re-attaches to that invocation and returns its current state
Same key, different body	`409`
New key while another invocation is still running	`423` — a session runs one invocation at a time
No key	A fresh, non-retry-safe invocation; the server generates a key

The effective key always comes back — in the Idempotency-Key response header, and in the CLI’s JSON output as idempotency_key — so you can reference or retry the invocation even when you did not supply one.

Agent configuration

The agent object defines behavior; agent_name names it. Every distinct configuration under one name becomes a revision, so you can tell which version of your agent produced a run. See agents and revisions.

{
  "model": { "name": "gemini-3.6-flash" },
  "system_prompt": "You triage support tickets. Be terse.",
  "tools": ["WEB_SEARCH"],
  "max_steps": 12,
  "mcp_servers": [
    {
      "name": "github",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "albus.sh/secrets/github-mcp" },
      "allowed_tools": ["search_issues"]
    }
  ]
}

Field	Meaning
`model.name`	Model identifier, e.g. `gemini-3.6-flash`. Required.
`model.provider`	Your own provider and credential. Omit to use the model Albus provides — see model providers.
`system_prompt`	System instructions. A server default applies when omitted.
`tools`	Built-in tools the model may call. `WEB_SEARCH` is the only one in alpha; an unknown name is rejected up front.
`max_steps`	Cap on model steps before the run stops.
`mcp_servers`	MCP servers whose tools are offered to the model.

In the CLI, the common fields have flags (--model, --system-prompt, --tool, --max-steps, --provider, --credential). Anything else — MCP servers, a provider URL override — goes in a JSON file:

albus sessions run support-1234 -p "triage this" \
  --agent-name support-triage --agent-file agent.json

--agent-file is the whole agent configuration and cannot be combined with --model, --provider, --credential, --system-prompt, --tool, or --max-steps. Put the model in the file instead.

Failure modes

Every one of these is a JSON body, not a bare status.

Status	Meaning	What to do
`400`	Invalid request — unknown tool, malformed MCP server, missing model	Fix the request; nothing ran
`401`	Credential missing, expired, or wrong for this API	`albus login`, or check `ALBUS_API_KEY` and the base URL
`403` `not_provisioned`	Account is not on the alpha roster	Request access
`409`	Idempotency key reused with a different body	Use a new key, or resend the original body
`423`	Another invocation is already running in this session	Wait for it, or retry the running invocation’s key
`429`	Organization hit its run quota	20 runs in alpha — email carlo@albus.sh
`502`	The run failed instead of replying	Body carries the failure kind and detail; check the audit log, then run again with a new idempotency key
`504`	Timed out waiting for the reply	The run continues; retry the same idempotency key

Note the difference between the two retries: reusing a key re-attaches to that invocation, so reusing the key of a failed run returns its failure again. Use the same key to recover a lost response (504, dropped connection), and a new key to actually run again. Albus does not retry a failed run for you — see alpha limitations.

Clean up

albus sessions delete support-1234

Getting started

Guides

For coding agents

Alpha

Reference

API reference

Session identity is yours to choose

Waiting for the reply

Idempotency

Agent configuration

Failure modes

Clean up

​Session identity is yours to choose

​Waiting for the reply

​Idempotency

​Agent configuration

​Failure modes

​Clean up

Session identity is yours to choose

Waiting for the reply

Idempotency

Agent configuration

Failure modes

Clean up