Albus

Run an agent session over an HTTP API: you send a prompt and an agent configuration, Albus executes the model loop in an isolated environment, connects the MCP servers you declare, and returns the assistant’s reply. A session keeps its history, so the next prompt continues the conversation. The agent can search the web and run commands in a sandboxed terminal, remember what matters across sessions in a memory group, and answer in a JSON shape you specify. Every invocation is recorded as a trace — its steps, model calls, tool calls, and token usage — readable by the key you ran it with.

Run your first session

Install the CLI

curl -fsSL https://albus.sh/install.sh | sh

albus login

Or create an API key for scripts and SDKs.

Run

albus sessions run my-first-session \
  --prompt "In one sentence, what is a session?" \
  --agent-name demo \
  --model gemini-3.6-flash

import os

from albus_sdk import Albus

with Albus(
    api_key=os.environ["ALBUS_API_KEY"],
) as albus:
    response = albus.sessions.run_session(
        id="my-first-session",
        user_prompt="In one sentence, what is a session?",
        agent_name="demo",
        agent={"model": {"name": "gemini-3.6-flash"}},
        wait_timeout_seconds=120,
    )

    print(response.result.message.content)

import { Albus } from "@albus-ts/sdk";

const albus = new Albus({
  security: { apiKey: process.env.ALBUS_API_KEY ?? "" },
});

const response = await albus.sessions.runSession({
  id: "my-first-session",
  waitTimeoutSeconds: 120,
  body: {
    userPrompt: "In one sentence, what is a session?",
    agentName: "demo",
    agent: { model: { name: "gemini-3.6-flash" } },
  },
});

console.log(response.result.message?.content);

curl --fail-with-body \
  --request POST "https://albus.sh/api/sessions/my-first-session?wait_timeout_seconds=120" \
  --header "Authorization: Bearer $ALBUS_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: first-run-1" \
  --data '{
    "user_prompt": "In one sentence, what is a session?",
    "agent_name": "demo",
    "agent": { "model": { "name": "gemini-3.6-flash" } }
  }'

No model API key of your own is needed for that run — Albus provides the default model. A session is a named conversation with an agent: you choose the identifier, and running the same identifier again continues the same conversation.

The wait makes the request long-poll until the assistant’s reply is available: wait_timeout_seconds over HTTP and in Python, waitTimeoutSeconds in TypeScript, --wait-timeout in the CLI. Omit it and you wait up to 30 minutes, the maximum; pass 0 to return as soon as the run is accepted.

The response is the session and the one message this invocation produced:

{
  "session": {
    "id": "my-first-session",
    "state": "DONE",
    "invocation_count": 1,
    "agent_name": "demo",
    "agent_revision": "b7f3c1a9d2",
    "created_at": "2026-02-10T18:03:44Z",
    "updated_at": "2026-02-10T18:03:51Z"
  },
  "message": {
    "cursor": 2,
    "invocation_key": "3f7c1e02-9a4b-4d81-b6de-5c2a70f18e44",
    "role": "assistant",
    "content": "A session is a named, ongoing conversation with an agent.",
    "created_at": "2026-02-10T18:03:51Z"
  }
}

message is the assistant’s reply, and is absent when the invocation has not answered yet — wait_timeout_seconds=0, or a wait that returned first. The whole conversation comes from GET /sessions/{id}, whose messages array holds every turn. The CLI prints the same object plus the run’s invocation_key, taken from the response header.

Continue the conversation

Run the same session identifier again. The agent sees the earlier turns.

albus sessions run my-first-session \
  --prompt "Now say that again in five words." \
  --agent-name demo \
  --model gemini-3.6-flash

Read it back

albus sessions list
albus sessions get my-first-session
albus sessions audit my-first-session --limit 20

get returns the messages; audit returns what happened inside the runs — model calls, tool calls, and outcomes. GET /traces/{invocation_key} returns the same invocation as spans, with token usage, and the console shows it under Traces.

Build an agent

From a bare model to tools, secrets, MCP servers, memory, traces, revisions, and the audit log — one step at a time.

Bring your own key

Run on your own model provider account.

Built-in tools

Web search, the terminal sandbox, and memory.

SDKs

The Python and TypeScript clients.

Using a coding agent? Point it at docs.albus.sh/agents/docs.md, or at llms.txt for the whole documentation index.

Getting started

Guides

Reference

API reference

Run your first session

Continue the conversation

Read it back

Next

Build an agent

Bring your own key

Built-in tools

SDKs

​Run your first session

​Continue the conversation

​Read it back

​Next

Build an agent

Bring your own key

Built-in tools

SDKs

Run your first session

Continue the conversation

Read it back

Next