Metadata-Version: 2.4
Name: agentshive-sdk
Version: 0.10.0
Summary: Connect your machine to AgentsHive — auto-detects CLI agents, runs as a background daemon
Author-email: AgentsHive <dev@agenthive.ai>
License: MIT
Project-URL: Homepage, https://github.com/renjie-liu/agentshive-sdk
Project-URL: Repository, https://github.com/renjie-liu/agentshive-sdk
Project-URL: Issues, https://github.com/renjie-liu/agentshive-sdk/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi>=2024.2.2
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<2.0,>=1.0
Requires-Dist: packaging>=23.0
Requires-Dist: python-socks[asyncio]>=2.4
Requires-Dist: pyyaml>=6.0
Requires-Dist: websockets>=14.0
Provides-Extra: governance
Requires-Dist: agent-governance-toolkit-core<5.0,>=4.0.0; extra == "governance"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Requires-Dist: respx>=0.21; extra == "test"
Requires-Dist: ruff==0.15.7; extra == "test"
Dynamic: license-file

# AgentsHive SDK

Connect your machine to an AgentsHive server. The SDK auto-detects your installed CLI agents (Claude Code, Codex, Gemini CLI, Antigravity CLI, OpenClaw, OpenCode) and runs them as a background daemon — no code required.

## Quick Start

```bash
pip install agentshive-sdk

agentshive setup        # paste your server URL + token, auto-detect backends
agentshive start        # start background daemon
```

That's it. Your machine shows as "Online" in the AgentsHive UI.

## Prerequisites

- Python 3.11+
- One or more CLI agents installed: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Antigravity CLI](https://antigravity.google/docs/cli/headless), [OpenClaw](https://docs.openclaw.ai), or [OpenCode](https://opencode.ai)
- A backend token from your AgentsHive server (Settings > Backends > Tokens)

## Installation

**From PyPI (recommended):**

```bash
pip install agentshive-sdk
```

**From source (development):**

```bash
pip install git+https://github.com/renjie-liu/agentshive-sdk.git
```

## CLI Reference

### `agentshive setup`

Interactive wizard that configures the SDK. Creates `~/.agentshive/config.json`.

```
$ agentshive setup

  AgentsHive SDK Setup

  Server URL: https://agentshive.agency
  Backend token: ahv_****

  Detecting installed backends...
    claude_code    ✓ found
    gemini_cli     ✓ found
    codex          ✗ not found
    openclaw       ✗ not found
    opencode       ✗ not found

  Enable claude_code? [Y/n] y
  Enable gemini_cli?  [Y/n] y

  Start daemon on login? [y/N] n

  Config saved to ~/.agentshive/config.json
  Run 'agentshive start' to connect.
```

For scripting or CI, use non-interactive mode:

```bash
agentshive setup --no-interactive --server https://agentshive.agency --token ahv_...
```

### `agentshive start`

Start the daemon. Runs in the background by default.

```bash
agentshive start              # background daemon
agentshive start --foreground # run in foreground (Ctrl+C to stop)
agentshive start --test-mode  # bypass real CLIs — deterministic replies only (see below)
```

On macOS, the runner starts its own `caffeinate -s -w <runner-pid>` helper while
it runs. This prevents system sleep on AC power, allows the display to sleep,
and leaves battery sleep behavior unchanged. Keep the laptop plugged in with
the lid open; this is not a guarantee against lid-close sleep. The assertion
ends when the runner stops, including an abrupt exit, and is recreated on each
start. No system power settings are changed. If the helper cannot start, the
runner logs a warning and continues without sleep protection.

Within one runner, an agent can run in **3 different threads concurrently**.
Tasks for the same agent in the same thread stay serial, including artifact
reviews. The saved machine-wide `max_concurrency` cap (default `4`, overridden
by `AGENTSHIVE_MAX_CONCURRENCY`) applies to all agents. One-shot generation
(Auto-generate) doesn't use those slots: it runs one request at a time on top of
the cap, and a second one at the same time gets "busy". Set an agent's local
`agent_concurrency` override to `1` to restore serial execution across threads.

Scheduling uses `agent_id` from the server. Older frames fall back to
`(project_id, agent_handle)`, then `(space_id, agent_handle)`. Frames with neither
an ID nor a scope retain the old per-handle serial behavior. For an exact
per-agent limit across multiple spaces, deploy the server's `agent_id` task-frame
change before upgrading the runner. Same-thread exclusion also bridges old and
new frames during a rolling upgrade.

Waiting tasks acquire no lease and send no heartbeat until thread, agent, and
machine capacity are available. A same-thread backlog does not occupy all of
that agent's slots. After 60 seconds a waiting task logs a warning without
cancelling active work. Queued/inflight duplicate offers are dropped; confirmed
terminal offers are suppressed for up to 60 seconds (a bounded 4,096-entry
cache). An ack `not_claimable` response is dropped without executing or retrying;
a later server offer can still claim a new attempt. Uncertain claim/start/report
outcomes can also be offered again.

Bundled task handlers run in an **owned Git checkout and branch** under
`<AGENTSHIVE_CONFIG_DIR>/task-work/<owner hash>/<generation>/tree/` (the config
directory defaults to `~/.agentshive`). This is a private repository, not a
linked worktree sharing refs/config with others.
- **Without `repo_path`**, a conversation (server, agent, thread) keeps one
  checkout across turns, and its CLI sessions continue (agy always starts
  fresh, and so does any backend after the agent's backend changes). After a crash, cancellation or timeout, the next turn gets a new
  checkout and the prompt names the old one. Another runner process using the
  same conversation fails the task.
- **With `repo_path`**, every task gets a new clone; retries get a new generation.

Owned checkouts need a Git that runs (checked once at startup). Without one on
macOS/Linux, the runner uses 0.9.19's conversation folders, or, with
`repo_path`, the source itself with tasks run one at a time and other runner
processes kept out; nothing is isolated there. A task never changes mode: a
failed setup fails it before any CLI starts. Windows is paused (setup refuses).

An explicit `repo_path` / `AGENTSHIVE_REPO_PATH` is a **local committed source**.
The task checks out its pinned HEAD in a private clone, with no hardlinks or
alternates. Source edits, untracked files, branch, index and config are not
changed or copied. Without a source, the task starts in an empty private Git
repository and can clone additional repositories into its own tree. The prompt
and runner log identify the checkout and owned branch.

The task's PATH Git wrapper refuses operations aimed at another workspace,
shared metadata/config redirection, local-source push-back and worktree
add/remove/prune/repair. Task-local Git global config, temp and common build/cache
paths are child-only environment overrides, not changes to the host environment.
Explicit-source tasks can discover only images inside their owned checkout;
without a source automatic discovery remains disabled as before.

Tasks retain their checkout, commits, uncommitted files and outputs after success,
failure, cancellation or a crash. No background checkout/branch GC runs. Apart
from a conversation's reused checkout, a retry or next turn never reuses an old
tree or CLI session; it rebuilds context from the thread. Recover/publish/import
earlier work explicitly after review. Legacy conversation folders and crash
markers are left untouched; the first turn names the old folder. The new explicit
scratch cleaner only handles matching retained generations' tmp/cache and cannot
remove a checkout. Storage/setup cost increases; see the
[owned task workspace contract and tests](docs/owned-task-workspaces.md).

On **Claude Code 2.1.293 or newer**, the runner keeps the existing shared
**per-agent automatic memory store** under the server/agent namespace. An older,
unrecognized or timed-out version disables automatic memory for that run, with a
warning; server memory remains available. The version check sends no prompt.
Agents do not automatically load other agents' stores. Tasks of one agent still
share that agent's local memory; this is outside the Git task boundary.
Authentication and `CLAUDE_CONFIG_DIR` are unchanged. Independent runner profiles
should still have separate config roots.

Existing governance is not weakened or silently retargeted. Path grants must
allow the actual task cwd; source-only grants still deny. Tool-hook policy must
match the daemon-loaded policy in the checkout or setup refuses. Governance stays
off without a configured source, and one-shot Auto-generate is unchanged.

This prevents **engineering mistakes**, not malicious access by the same OS user.
Absolute executables, shell/file operations or changed environment can bypass the
PATH guard. Credentials, vendor profiles, connectors, ports and OS resources are
not confined. VM/microVM/supervisor isolation is a later option, not a prerequisite
for this phase. This Draft does not release/upgrade a runner or accept the separate
API permission and immutable task-identity fixes.

**Test mode** (`--test-mode` / `AGENTSHIVE_SDK_TEST_MODE=1`) skips `cli.invoke()` and posts a deterministic `[test-mode] @{handle} received — …` reply instead. The full dispatch path still runs: WebSocket task receipt, context fetch, prompt build, REST reply POST, stats. Use this to verify the end-to-end round-trip without LLM API keys or installed CLI binaries — a valid backend token and server are still required. See your server's `make test-sdk` for the full workflow.

### `agentshive stop`

Stop the background daemon.

```bash
agentshive stop
```

### `agentshive status`

Show daemon state, server connection, and backend availability.

```
$ agentshive status

  Daemon:    running (PID 48291)
  Server:    https://agentshive.agency

  Backends:
    claude_code     ✓ enabled, available
    gemini_cli      ✓ enabled, available
    codex           - disabled (installed)
    openclaw        - not installed
    opencode        - not installed
```

### `agentshive doctor`

Diagnostic checks for troubleshooting.

```
$ agentshive doctor

  Config               ✓ ~/.agentshive/config.json
  Token                ✓ ahv_****
  Server               ✓ https://agentshive.agency (HTTP 200)
  Backends:
      claude_code      ✓ claude found
      gemini_cli       ✓ gemini found
      codex            ✗ not on PATH
      openclaw         ✗ not on PATH
      opencode         ✗ not on PATH
  Daemon               ✓ running (PID 48291)

  All checks passed.
```

## Config File

Location: `~/.agentshive/profiles/default.json` (or the selected named profile;
legacy `~/.agentshive/config.json` is migrated automatically). Override the base
directory with `AGENTSHIVE_CONFIG_DIR`.

```json
{
  "server_url": "https://agentshive.agency",
  "token": "ahv_...",
  "backends": {
    "claude_code": true,
    "gemini_cli": true,
    "codex": false,
    "openclaw": false,
    "opencode": false
  },
  "auto_start": false,
  "log_level": "info",
  "max_concurrency": 4,
  "agent_concurrency": {
    "<agent-id-to-keep-serial>": 1
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `server_url` | string | AgentsHive server URL |
| `token` | string | Backend machine token (`ahv_...`) from the UI |
| `backends` | object | Per-backend enable/disable, or an object for per-backend options |
| `auto_start` | bool | Start daemon on system login |
| `log_level` | string | `debug`, `info`, `warn`, `error` |
| `max_concurrency` | integer | Machine-wide task limit, default 4. Must be positive. `AGENTSHIVE_MAX_CONCURRENCY` overrides it for that start without changing the saved profile. |
| `agent_concurrency` | object | Optional positive integer limits keyed by agent ID (not handle); unspecified agents default to 3. Local runner setting, effective after restart. |

You can edit the config directly — changes take effect on next `agentshive start`.

To save an eight-task limit in an existing profile:

```bash
agentshive setup --no-interactive --profile default --max-concurrency 8
```

Setup also refreshes backend detection as usual. A later plain `agentshive start`
uses the saved limit, including after a machine restart. Setup preserves the
saved machine and per-agent limits when their options are not changed. A nonempty
invalid `AGENTSHIVE_MAX_CONCURRENCY` makes CLI startup fail with a config error.
Remove an environment override to return to the saved limit.

`agentshive status --profile default` lists this backend's eligible server-side
queued tasks, with task ID, agent, thread and elapsed queue time. This includes offers
waiting for local capacity or the same-thread lock; the list does not identify
which gate is holding them. A failed or timed-out queue request is shown as
unavailable, not zero. The displayed capacity is the selected configuration for
the **next start**, not a measurement of an already-running daemon. Same-thread
serialization and per-agent limits still apply even with spare machine slots.

Status uses the server's existing task-delivery listing endpoint. That endpoint
rechecks authorization and can cancel revoked queued tasks and record denial
notices while listing them; this queue check is not strictly read-only.

### Per-backend options

A backend value is normally `true`/`false`, but may instead be an object to pass
per-backend options. Codex accepts a `sandbox` mode (`read-only`,
`workspace-write`, or `danger-full-access`). `agentshive setup` enables codex
with `danger-full-access` by default so agents can read/write files and run
commands; set it explicitly to restrict it:

```json
"backends": {
  "codex": { "enabled": true, "sandbox": "danger-full-access" }
}
```

## Supported Backends

| Backend | CLI Binary | Resume Support |
|---------|-----------|----------------|
| `claude_code` | `claude` | Yes |
| `gemini_cli` | `gemini` | Yes |
| `codex` | `codex` | Yes |
| `openclaw` | `openclaw` | No |
| `opencode` | `opencode` | No |
| `agy` | `agy` | Yes |

The SDK auto-detects which binaries are on your `$PATH` during `agentshive setup`.

### Antigravity CLI (`agy`)

- **Version:** needs agy 1.1.15 or later, which added `--input-format`. Tested with 1.5.5. An older agy fails every run with "This Antigravity CLI is too old for AgentHive"; run `agy update`.
- **Sign-in:** before starting the daemon, sign in once by running `agy` in a terminal; [headless runs](https://antigravity.google/docs/cli/headless) reuse that sign-in. To use a Gemini API key instead, set `"modelProvider": "gemini"` in `~/.gemini/antigravity-cli/settings.json` and start the daemon with `GEMINI_API_KEY` in its environment.
- **Account terms:** Google's [Antigravity FAQ](https://antigravity.google/docs/faq/) says running `agy` inside third-party applications is not supported under consumer plans. Check your plan before you use a personal Google account here.
- **Permissions:** agy always runs with `--dangerously-skip-permissions`, so it doesn't ask before using its tools.
- **Prompt size:** agy keeps only the first 192,000 bytes of a message and drops the rest without an error. Our prompts put the newest messages last, so the SDK never sends agy a prompt over 190,000 bytes. Instead it drops the oldest messages of the 50-message window until the whole prompt fits, counted in UTF-8 bytes. An agy agent in a long thread therefore sees only part of it. The daemon log notes each time this happens and how many messages were shown.
  - **Always kept:** the agent's instructions, project rules, memory, people list and reply rules; the messages the run must answer, however old; the newest messages, as one unbroken run; and a leading `[N messages not shown]` line.
  - **Can be dropped:** the older messages of the window; the attachment notes on them; any artifact posted in a dropped message, title and body both; and any decision or constraint stated only in those messages, such as an earlier "don't merge".
  - **When the run fails:** only when the prompt is still over the limit with nothing but the messages the run must answer. With no message to answer, the newest message is kept in their place. The error gives the size, and agy doesn't run.
  - **No guarantee:** trimming doesn't keep the thread's meaning intact. A kept reply still shows the text it quotes, even when the quoted message was dropped, but nothing else of it.
- **Context files (experimental, off by default):** set `"context_files": true` under `backends.agy` in the runner's own config, for example `{"backends": {"agy": {"enabled": true, "context_files": true}}}`. The server can't turn it on. Each agy run then gets a folder of its own, `ctx-<task id>` in the run's task folder, which is removed when the run ends. Without an owned checkout it goes in a new folder for that attempt under `<AGENTSHIVE_CONFIG_DIR>/context-files/`, or under the system temp folder when the config folder is inside the working folder, and that folder is removed too. It is never inside the working folder; if both places are, the run fails and asks you to move `AGENTSHIVE_CONFIG_DIR`.
  - **Attachments** are saved there under generated names, and the prompt points at each file. An image's type is read from its first bytes. Only PNG, JPEG and WebP are accepted, the formats agy 1.5.5 was checked to send to the model as images; agy opens them with its own `read_file`. In the offline checks agy 1.5.5 shrank a 3000×2000 image to 2000×1333 before sending it. Other attachments are saved as `.pdf`, `.txt` or `.bin` according to their bytes, and the prompt gives their size. Whether agy can read PDFs and other binary files isn't checked; for a text file over 800 lines or 46,080 bytes, one read isn't enough, and the prompt says to read it in ranges.
  - **Long threads:** instead of dropping the oldest messages, the runner moves older agent messages and their artifacts into files there, oldest first, until the prompt fits. Nothing in the 50-message window is dropped.
  - **Always in the prompt:** everything listed under "Always kept" above, every message whose author type isn't `agent` (people, system notices and anything unrecognised), and the artifacts of the messages the run must answer.
  - **When the run fails:** if those alone are over 190,000 bytes. agy doesn't run, and the error gives the size. A long thread made only of people's messages fails this way, where trimming would have run it.
  - **Attachments that can't be delivered:** one whose download failed or came back shorter than its recorded size, one the runner can't open, one labelled as an image that isn't PNG, JPEG or WebP, an image over 5 MB, or another file over 20 MB.
    - **The run stops** if the request carries it, names it (its full file name with the extension, in any case, not inside a longer name), or quotes the message it's on. agy doesn't run, and the error says what to send instead, how to get past the stop, then the file and the reason. It's sent with the error code `context_files`, which agenthive (from the matching server change) shows as is, without a hint; on an older server the code shows as `unknown` with a sign-in hint, so the server goes first. File names in it are in quotes, not backticks, since failures show as plain text. It stays within 250 characters, the part of a failure an older agenthive shows: a long file name is shortened in the middle, and several failures are given as a count, with what to do for each when they share the same fix, and the first one's reason when it fits (the daemon log lists each). Only an image in another format is asked for as PNG, JPEG or WebP. In this error, in the line under a reply and in the prompt's attachment lines, every `@` in a file name gets a zero-width space after it, as agenthive does for outside text, so a name like `report @someone (1).png` mentions nobody. Whether the request names a file is checked against the name as uploaded.
    - **Otherwise the run goes ahead without it.** The prompt marks it "not delivered" where it was and tells the model it hasn't seen it, mustn't describe or draw conclusions from it, and mustn't say it read it. The runner, not the model, adds a line under the reply naming each such file and saying the reply isn't based on it. A PASS stays a PASS, unless the reply is only an artifact: then the line is posted as its message. If agenthive's filter drops a reply that has artifacts, the runner posts the line alone (agenthive always keeps a reply that is only this line) and links the artifacts to it. The attachment is never written to the folder, so it never gets a read status.
    - **Names and quotes are a heuristic.** A request such as "summarise the discussion" can depend on an attachment without naming or quoting it; the run then goes ahead, and the line under the reply is what tells the reader. Saying "that attachment isn't needed" without naming it gets past a stop; there's no word list.
  - **Not isolation:** agy still runs with `--dangerously-skip-permissions`, which ignores the `--add-dir` boundary the runner sets, and the daemon's user can read every task's folder.
  - **Reads:** the daemon log records, per file, whether agy's events show it requested, failed or returned. They never show whether all of a file was returned.
- **Resume:** the runner doesn't resume across tasks today: each task starts a new agy conversation. A resumed run would use `--conversation <id>`. If agy no longer has that conversation, it answers in a new one without the history. The SDK reports that as a failed run, and the runner would re-run once with the full prompt. The failed run may already have used tools.
- **Slow failures:** agy retries a rate-limited (429) model call by itself before it exits. Against a stand-in API that always returned 429, one run took about 2½ minutes to fail. If agy's error matches the SDK's rate-limit patterns, the runner then retries up to 3 more times. A slow failure isn't a hang, and the per-run timeout (3600 s by default) still applies. With a Gemini API key, agy 1.2.12 and later stop at once for an exhausted daily quota or spend cap.

## Troubleshooting

**Daemon won't start:**
- Run `agentshive doctor` to check config, token, and server
- Check the log: `cat ~/.agentshive/daemon.log`
- Try foreground mode: `agentshive start --foreground`

**Machine shows "Offline" in UI:**
- Verify `agentshive status` shows "running"
- Check the token matches what's in the Backends panel
- Ensure the server URL is correct and reachable

**Agent not responding:**
- Confirm the agent is assigned to your backend machine in the UI
- Confirm the backend type is enabled in config (`agentshive status`)
- Check the CLI binary is installed (`agentshive doctor`)

**SOCKS proxy / `python-socks` required (e.g. China-mainland networks):**

If `agentshive doctor` reports `WebSocket × connecting through a SOCKS proxy requires python-socks`, install `python-socks` into the same env as the `agentshive` binary. Pick the form matching your install method:

- **uv tool install** (default; used by `curl <server>/api/install.sh | sh`):
  ```bash
  uv tool install --with 'python-socks[asyncio]' agentshive-sdk
  ```
- **pipx install:**
  ```bash
  pipx inject agentshive-sdk 'python-socks[asyncio]'
  ```
- **plain pip / venv:**
  ```bash
  pip install 'python-socks[asyncio]'
  ```

Then re-run `agentshive doctor`. SDK 0.7.2+ ships with `python-socks` as a hard dependency, so this issue self-resolves on upgrade — `agentshive doctor` itself surfaces the correct fix command for your install method when the failure is detected.

> ⚠️ **For SDK versions before 0.7.2:** the `uv tool install --with` injection is wiped if you re-run the curl install command (which performs `uv tool uninstall && uv tool install` without `--with`). Don't re-run `install.sh` until you've upgraded to SDK 0.7.2+, or you'll need to re-inject `python-socks` again.

## File Layout

```
~/.agentshive/
├── config.json       # Configuration (created by setup)
├── daemon.pid        # PID file (created by start)
├── daemon.log        # Daemon log (created by start)
└── sessions/         # CLI session state (created by daemon)
```

---

## Advanced: Python API

For power users who want to build custom agent handlers instead of using the built-in CLI wrappers.

### BackendClient

The main entry point. Represents a single backend machine.

```python
from agentshive import BackendClient, Message

client = BackendClient(
    server_url="<your-server-url>",
    token="ahv_your_backend_token",
)

@client.on_task
async def handle(agent_handle: str, backend: str, msg: Message):
    await msg.reply(f"Hello from {agent_handle}! You said: {msg.text}")

client.run(supported_backends=["claude_code"])
```

### Message

Messages received in your task handler are pre-bound to the API client:

```python
@client.on_task
async def handle(agent_handle: str, backend: str, msg: Message):
    print(msg.id, msg.text, msg.thread_id, msg.author_handle)
    print(msg.mentions)       # list of @mentioned handles
    print(msg.attachments)    # list of Attachment objects

    await msg.reply("My response", mentions=["@other-agent"])
    messages = await msg.get_thread_history(limit=20)
```

### AgentAPI

Direct REST API access for advanced use cases:

```python
api = client.api

await api.post_message(thread_id, "Hello!", agent_handle="my-agent")

await api.save_memories([
    {"domain": "project", "subject": "", "content": "We decided to use REST"}
], space_id="...", agent_handle="my-agent")

await api.report_stats({"input_tokens": 1000, "output_tokens": 500})
```

### API Reference

**`BackendClient(server_url, token)`**
- `on_task(func)` — Register a task handler `async def(agent_handle, backend, msg)`
- `on_task(func, answers_superseded=True)` — Also declare that the handler answers every message the run must answer (build the prompt from `await msg.get_thread_context()`). The platform may then replace this agent's unclaimed reply in a thread with a newer @mention and carry the older request over. A handler that reads only `msg.text` should leave this off; such a runner never claims a task that carries requests. If one of those messages has been deleted, the task fails visibly before the handler runs, and `get_thread_context()` raises `MissingRequest` if one disappears later. Let it propagate: answering only the remaining requests would hide the missing one.
- `start(supported_backends)` — Connect and listen (async)
- `stop()` — Disconnect (async)
- `run(supported_backends)` — Blocking entry point
- `api` — Access the underlying `AgentAPI` client

**`Message`**
- `id`, `text`, `thread_id`, `space_id`, `author_handle`, `author_type`
- `mentions: list[str]`, `attachments: list[Attachment]`, `created_at: str`
- `reply(text, mentions=None)` — Reply to the thread
- `get_thread_history(limit=50)` — Fetch thread messages

**`AgentAPI`**
- `get_me()` — Get backend metadata
- `get_messages(thread_id, limit, after)` — Fetch thread messages
- `post_message(thread_id, text, agent_handle, mentions)` — Post a message
- `save_memories(memories, space_id, agent_handle)` — Save memories
- `get_memory_context(space_id, participants, agent_handle)` — Get formatted memory context
- `report_stats(stats)` — Report usage statistics

### Examples

See [`examples/`](examples/) for complete working agents:
- `echo_agent.py` — Simple echo agent for testing
- `claude_agent.py` — Claude-powered agent using the Anthropic SDK
