awcompact

Aither ADK — Build AI Agent Fleets

<!-- aither-header:start GENERATED from the ecosystem registry. Edits here are overwritten; change the registry instead. -->

Docs · Source · pip install awdk · The Aither World

The Aither World is an operating system for agents — a Linux you can hand to one, the runtimes it works in, and the tools it works with. awnix is the Linux underneath it; awdk is one of its 67 bricks — each installs on its own, runs offline, and needs no account.

Start here: Point it at a backend you already pay for and run one agent loop.

<!-- aither-header:end -->

<!-- mcp-name: io.github.Aitherium/awdk -->

3 lines of code. Any backend. Local or cloud. Zero lock-in.

Aither ADK is a Python SDK + CLI for building AI agents that run on your hardware — a single helpful agent or a coordinated fleet that delegates work to each other. Agents get tools, persistent knowledge-graph memory, safety filtering, and effort-based model routing out of the box. Swap the LLM backend at runtime — your GPU, Ollama, llama.cpp, or any cloud API — same code, same agents.

pip install awdk
adk quickstart                                    # auto-detect hardware, set up inference
adk init my-agent && cd my-agent && python agent.py

The package is awdk; the command is adk (awdk is the same command, and python -m adk always works). Windows, "adk is not recognized"? pip put the command in a Scripts folder that is not on PATH — its warning names the folder. Add it once, then open a new terminal:

$s = python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
[Environment]::SetEnvironmentVariable('Path', "$([Environment]::GetEnvironmentVariable('Path','User'));$s", 'User')

---

Get running in 60 seconds — pick your path

You have…	Run this	You get
Nothing — not even Python	one-line installer (below)	isolated env + first-run wizard
No GPU, no API key	adk bonsai-local	Bonsai running free, offline, on CPU — pulls ~300MB image, serves on :8090
A GPU (6 GB+)	adk quickstart	auto-detected vLLM/Ollama, models pulled, ready to chat
Just an API key	adk quickstart --cloud	cloud inference (Anthropic / OpenAI / DeepSeek)
A whole LAN of machines	adk deploy grid	multi-machine effort-routed inference

The no-Python one-liner — sets up an isolated environment (via uv) and launches the wizard:

# macOS / Linux
curl -fsSL https://aitherium.com/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://aitherium.com/install.ps1 | iex"

Then, whichever path you took:

adk start          # chat with your agent (zero config)
adk doctor         # something wrong? this names it

Using an AI coding agent (Claude Code, Cursor, Copilot)? Paste the Agent Setup Prompt into your session — it walks the agent through install, auth, inference, and the path from zero to fleet. There's also llms.txt / llms-full.txt for tools that ingest those.

---

Contents

• New here? The five concepts
• Documentation map — every guide, linked
• Subagents — drive Claude Code, Codex, and eight more — real binaries, scoped, torn down
• Quick Start
• Aither Hearth: your agent, on your phone — serve, channels, approvals, receipts
• Bonsai: an agent on literally anything
• Reasoning capture & code intelligence — external thinking, omp interop, DeepSeek Coder
• Setting Up Inference
• Building Agents
• Agent Fleets
• Agents & Packs
• CLI Reference
• The Aitherium ecosystem
• Environment Variables · Examples · License

---

New here? The five concepts

Everything in the ADK hangs off five ideas:

1. Agent — AitherAgent("aither"). One object: await agent.chat("...") is the whole API. It has a persona, tools, and memory.
2. Backend — where inference runs. Local (vLLM / Ollama / llama.cpp / Bonsai) or cloud (Anthropic / OpenAI / DeepSeek / Aitherium gateway). Switchable at runtime, mid-session.
3. Effort routing — every call carries a 1–10 effort level; cheap calls go to small fast models, hard calls go to the big reasoning model. Automatically. You never pick a model per call again.
4. Memory — a local SQLite knowledge graph that auto-ingests entities and relations from every conversation. Hybrid keyword + semantic search. No external services.
5. Fleet — multiple agents that can call each other via the built-in ask_agent tool. One YAML file, one adk-serve command, and you have an orchestrator delegating to specialists.

If you only remember one thing: agent.chat() is the agent. Everything else is configuration.

Documentation map

I want to…	Read this
Drive Claude Code / Codex / OpenCode / Aider from one shell	AWSH-OMNISHELL-PLAYBOOK.md — install → detect → daemon → UI, verified end to end
Build a real agent or publish a pack	docs/AGENT_DEV_GUIDE.md — the golden path + gotcha checklist
Self-host the full managed-agent experience	QUICKSTART_SELF_HOSTED.md — adk onboard --quick
Operate a self-hosted node long-term	docs/SELF_HOSTING_RUNBOOK.md
Run inference across several machines	GRID_SETUP.md
Wire up a specific LLM provider	docs/providers/ — DeepSeek, Kimi, OpenAI-compatible, local AitherOS
Give my agent a persistent identity/persona	docs/PERSONA.md · `adk soul import	export`
Understand the world-model layer	docs/WORLD_MODEL.md
Connect agents across machines (relay)	docs/AITHERRELAY_GUIDE.md
Run a private, local-only companion	PRIVATE_COMPANION.md
Reach my own agent from my phone (Aither Hearth)	docs/agent-home.md — adk home serve, channels, approvals, receipts
See working code	examples/ — five runnable scripts
See what changed	CHANGELOG.md
Browse rendered docs	aitherium.github.io/awdk

Interoperability

Aither agents speak three protocols for seamless integration with external systems:

1. ACP (Agent Client Protocol) — IDE Integration

Connect your agent to JetBrains, Zed, VS Code, or any ACP-compatible editor over JSON-RPC 2.0 stdio.

adk acp serve                          # Serve your agent to an editor

• Harness ID: acp (registered in adk.harnesses.registry)
• Transport: STRUCTURED_BIDI (JSON-RPC 2.0)
• Usage: Agents appear as room participants in AitherShell, driven by editors that speak ACP v2

2. A2A (Agent-to-Agent) — Remote Agent Integration

Map remote A2A agents (Google A2A v0.3.0 compatible) as room participants with full task lifecycle visibility.

from adk.a2a_adapter import A2AAdapter

adapter = A2AAdapter(room_id="main", remote_agent_id="foo")
adapter.on_task_submitted("task_001", "what is AI?")
adapter.on_task_working("task_001", "thinking...")
adapter.on_task_completed("task_001", "AI is...")

• Module: adk.a2a_adapter.A2AAdapter
• Events: Task lifecycle maps to AitherEvents (orchestration + cognition pillars)
• Flux codes: a2a.s (submit), a2a.u (update), a2a.d (done)
• Actor kind: a2a — remote agents appear with their own identity in rooms

3. MCP-UI — Render Blocks as Resources

Serve agent-generated RenderBlocks (server-driven UI: tables, forms, charts, approval gates) via the MCP resource protocol using ui:// URIs.

from adk.mcp_ui_resources import RenderBlocksMCPServer, create_table_block, create_scores_block

server = RenderBlocksMCPServer()
blocks = [
    create_table_block(columns=["Issue", "Severity"], rows=[[...], [...]]),
    create_scores_block({"security": 0.92, "style": 0.78}),
]
uri = server.from_agent_response("reviewer", "task_123", blocks)
# uri -> "ui://agent/reviewer/task_123"

• Module: adk.mcp_ui_resources.RenderBlocksMCPServer
• Block types: 24 primitives (markdown, header, table, code, form, approve, slider, file_upload, etc.)
• Schema validation: Block schemas are kept at parity with the AitherOS RenderBlocks protocol, so a block emitted here renders identically in any AitherOS surface
• MIME type: application/vnd.aitheros.renderblocks+json
• Integration: Mount into FastAPI, use in MCP clients that understand ui://

---

The aw packages — three questions adk can ask about a repository

adk is the agent runtime; three small, independent packages give it the facts it would otherwise have to guess at. Each answers a different question, each installs on its own, and none of the three requires the others:

Package	Knows	The question it answers
awgraph	what the code is, and what depends on what	Where is this symptom coming from?
awgit	what changed, and who is editing it	Is this an in-flight edit someone else owns?
awrelay	who found what, and who still needs to hear it	Who do I tell?

pip install awgraph awgit awrelay   # or any one of them, alone

Used together, an agent can find a symptom with awgraph, check whether it is an in-flight edit with awgit, and tell the agent already working that file with awrelay — three questions a solo grep-and-guess loop cannot ask at all. The failure they remove is not "the agent was wrong"; it is two agents editing the same file without knowing, and a finding that died in a transcript nobody read.

Each publishes an aither-manifest.json beside its page, and each page renders the others live from those manifests — a project whose manifest is missing shows as unknown rather than silently disappearing: awgraph · awgit · awrelay.

---

Subagents — drive Claude Code, Codex, and eight more

Just want it working? → AWSH-OMNISHELL-PLAYBOOK.md. Install → detect → start the daemon → use it, with verified output at each step. The step people miss is that the harness daemon has to be running: without it the desktop app reports "No harnesses reported by the daemon yet", which reads as a missing feature rather than a stopped process.

Your agent can delegate a task to another coding agent's real product — not a reimplementation of it against the raw API.

That distinction is the whole design. Rebuilding Claude Code's behaviour yourself means inheriting none of its skills, hooks or account handling, and then chasing a product that ships faster than you can track it. So the ADK resolves the real binary on PATH (honouring PATHEXT, so the Windows .cmd shim works), runs it headless with an explicit tool scope, feeds the prompt over stdin — never argv, which is visible in the process table — gives each run its own config dir so concurrent subagents can't corrupt one another's state, and tears down the process tree on timeout.

adk shell harnesses          # what can this machine drive, and how to get the rest
adk shell new --harness claude
adk shell send  <id> "refactor the retry logic in billing/"
adk shell attach <id>        # watch it work
adk shell kill  <id>         # teardown

adk shell harnesses on a typical box:

ID           INSTALLED  TRANSPORT         DESCRIPTION
claude       yes        structured-bidi   Anthropic Claude Code — bidirectional stream-json, full tool use
gemini       yes        oneshot-per-turn  Google Gemini CLI — one process per turn, stream-json output
terminal     yes        pty-stream        A real shell on this host behind a pseudo-terminal (pwsh/bash)
sandbox      NO         pty-stream        A real Linux TTY inside a dev-workspace container
                                          -> Install Docker Desktop
acp          yes        structured-bidi   JSON-RPC 2.0 stdio harness for JetBrains/Zed/VS Code editors
codex        NO         oneshot-per-turn  OpenAI Codex CLI — one process per turn (codex exec --json)
                                          -> npm i -g @openai/codex
aider        NO         oneshot-per-turn  Aider — pair-programming CLI (one process per turn)
                                          -> pip install aider-install && aider-install
opencode     NO         oneshot-per-turn  OpenCode — open-source coding agent (one process per turn)
                                          -> npm i -g opencode-ai

Ten harnesses are declared; the ones you haven't installed say so and tell you the command. It never silently pretends the world is Claude-only — a harness you don't have is a missing install, not a missing feature, and the difference is printed rather than guessed at.

Harnesses are data, not drivers

A per-agent runner does not scale — you end up with claude_runner.py, codex_runner.py, gemini_runner.py, each drifting. So a harness is a row:

HarnessSpec(
    id            = "codex",
    label         = "OpenAI Codex CLI",
    transport     = Transport.ONESHOT_PER_TURN,
    binary        = "codex",
    version_argv  = ["--version"],
    install_hint  = "npm i -g @openai/codex",
    json_lines    = True,
    build_argv    = lambda spec, launch: [spec.binary, "exec", "--json", launch.prompt],
)

Four transports cover every agent CLI shipping today: structured-bidi (a persistent bidirectional stream-json session), oneshot-per-turn (a fresh process per turn), pty-stream (a real TTY behind a pseudo-terminal), and http-stream (a remote agent over SSE). Adding an eleventh harness is a table entry, not a new module.

Scoped by construction

A subagent is launched with an explicit allow-list, and the runner re-validates it fail-closed rather than trusting the caller:

from adk.claude_runner import ClaudeRunner, RunScope

runner = ClaudeRunner()
scope  = RunScope(allowed_tools=["Read", "Grep", "Glob"])      # read-only
rec    = runner.submit(task="audit error handling in ./api", scope=scope)

rec = runner.get(rec.run_id)          # queued | running | completed | failed | cancelled
print(rec.result_text)                # one task out, one answer back
runner.kill(rec.run_id)               # teardown, whole process tree

The scope becomes --allowedTools on the real CLI, so a subagent asked to audit code cannot write to your disk — enforced by the product you delegated to, not by a prompt asking it nicely.

---

Quick Start

1. Set up inference (one command)

adk quickstart detects your hardware, pulls the right models, configures backends, and gets you chatting:

pip install awdk
adk quickstart                 # local GPU: detect → pull models → serve
adk quickstart --cloud         # no GPU: enter an API key (Anthropic / OpenAI / DeepSeek)
adk start                      # start chatting

Either way you get the full harness: tools, skills, memory, and multi-agent coordination.

Want the full self-hosted, managed-agent experience (local LLM → customize a pack → enroll your machine → manage it from the portal)? See QUICKSTART_SELF_HOSTED.md — adk onboard --quick does it in one command.

2. Your first agent

import asyncio
from adk import AitherAgent

async def main():
    agent = AitherAgent("aither")              # auto-detects vLLM/Ollama on localhost
    response = await agent.chat("Hello! What can you help me with?")
    print(response.content)

asyncio.run(main())

3. Grow into a fleet

The package ships one ready agent — aither, the orchestrator. Add specialists by installing a ready-made pack, or by defining your own. Any agent can then call any other through the built-in ask_agent tool.

# install a ready-made specialist (web research)
adk install pack:openclaw

# define a fleet — the shipped orchestrator + an installed pack + your own agent — and serve it
cat > fleet.yaml <<'YAML'
orchestrator: aither
agents:
  - identity: aither                  # ships with the package
  - identity: openclaw                # installed above
  - name: reviewer                    # your own — just give it a prompt
    system_prompt: "You review code for bugs and security issues."
YAML
adk-serve --fleet fleet.yaml --port 8080

4. Earn tokens by volunteering

Earn Aitherium tokens by contributing compute to the community embedding pool:

adk volunteer enroll                   # register as a volunteer (tenant from adk login)
adk volunteer serve                    # download the embedding model & start llama-server
adk volunteer start                    # loop: claim batches → embed → submit → earn tokens

Reputation, verified batches and earnings show in the Volunteer Compute panel of the tenant workspace (dgg.aitherium.com) and in adk volunteer status.

Why Aither?

Locked appliances	Aither ADK
Their hardware, their cloud	Your hardware, your rules
1 AI assistant	Build a fleet — start with aither, add ready-made packs or your own; they delegate to each other
Their model picks	Any model — route by effort level automatically
Data on their servers	Data stays on your machine
Closed system, monthly fee	Open-core (BSL-1.1) — free, runs entirely on your box
Locked to one provider	Runtime backend switching — swap LLM mid-session
Cloud-only reasoning	Hybrid reasoning — local orchestration + cloud deep thinking

---

Aither Hearth: your agent, on your phone

adk home runs one personal agent on your machine that answers only you, on the chat apps you already use. The same CLI is installed as aither-hearth.

adk home init --name pip                  # ~/.aither/agent-home: persona, model, memory
adk home model --byo anthropic            # or --local ollama | llamacpp | bonsai
adk home model --check
adk home signin                           # Sign in with Aitherium
export HEARTH_TELEGRAM_TOKEN=...          # a Telegram bot token from @BotFather
adk home serve --channels telegram --pair # prints a 6-digit code: DM it to the bot

• Serve and channels. adk home serve answers you on the relay, Telegram, Discord, Slack, email, WhatsApp and SMS: every channel whose credentials are in the environment (adk home channels shows which), or exactly the ones in --channels. Pair another channel by sending pair <channel> from one that is already paired.
• It messages you first. Reminders and follow-ups you ask for arrive on the channel you last used.
• Approvals. Anything that sends, books or adds (an email, a calendar event, a to-do, a recurring follow-up) waits for your yes <code> on the channel the request arrived on.
• Receipts. Every action is appended to a signed, hash-chained log: adk home receipts --verify exits 0 intact, 1 tampered, 2 cannot judge. adk home trust status shows what is enforced.
• Connectors (optional). After adk home signin, a workspace admin connects a Google account at api.aitherium.com/admin?tab=connections (admin-only); the agent can then read your agenda and mail, and add to them only after an approval. Microsoft 365 is not available yet.
• Local window. adk home say "...", adk home events and /hearth in adk-shell talk to the running serve over 127.0.0.1 instead of starting a second agent.

Everything above is free. The paid agent-home pack adds learning that carries across game sessions and more than one agent at a time. Full guide: docs/agent-home.md.

---

Bonsai: an agent on literally anything

No GPU. No API key. No account. Nothing leaves your machine.

Bonsai is Aitherium's family of ultra-compact models built to make agents sovereign by default — they run on hardware everyone already owns. The 1-bit Bonsai-27B runs on a plain CPU with 4 GB of RAM; Bonsai-4B runs in 2 GB (Android via Termux, Raspberry Pi Zero). Agents on Bonsai get the full harness — tool calling, memory, safety, fleets — not a demo mode.

adk bonsai-local                # one command: Docker pulls the image + serves Bonsai-27B on :8090
adk --backend bonsai-local      # point your agents at it

Why this matters, concretely:

• Free forever, offline after setup — one network pull for the model/image, then a fully working agent with zero external dependencies. Air-gapped targets work too: fetch the artifacts on a connected machine and sideload them.
• Tool calling works — Bonsai drives the same @tool functions, ask_agent delegation, and pack skills as the big models.
• Private by construction — no key means no telemetry decision to trust; there is simply no wire out.
• A floor, not a ceiling — start on Bonsai today, add a GPU tier or a cloud reasoning backend later; your agent code does not change.

When you outgrow it, effort routing lets you keep Bonsai for the cheap calls and send only the hard ones somewhere bigger — see hybrid profiles.

---

Reasoning capture & code intelligence

Three packs added in 3.2.0. Each exists because of something the platform's chat models structurally cannot do.

External thinking — get the chain of thought back

Providers stopped returning raw reasoning. The recovery, from Oh My Pi's externalThinking (MIT), needs no jailbreak: turn the model's native reasoning channel off, then give it a tool whose only parameter is a string described as a private scratchpad. It keeps reasoning — into the tool call, which the API returns in plaintext. What comes back is the model's own shorthand, not a written-for-an-audience summary.

from adk.packs.omp_thinking import reconcile, deep_think_directive

model = {"api": "anthropic-messages", "reasoning": True,
         "thinking_requires_effort": True, "thinking_suppress_when_off": True}

reconcile(agent._tools, model)          # arms `deep_think` only if the model can take it
print(deep_think_directive(8)["directive"])   # the effort number, aimed at the scratchpad

Two things this pack refuses to do, both deliberate:

• It refuses unknown and incapable models. A model that cannot suppress its native channel gets both channels or a rejected request, so it is refused and counted, never probed hopefully.
• It disarms on model swap. Whether the scratchpad is legal is a property of the model, not the session, so reconcile() must run on every swap. Arming it once at startup is correct right up until someone changes models.