Agentao (Agent + Tao)

   ___                      _
  / _ \ ___ _ ___  ___  ___| |_  ___  ___
 /  _  // _` / -_)| _ \/ _ \  _|/ _` / _ \
/_/ |_| \__, \___||_// \___/\__|\__,_\___/
        |___/        (The Way of Agents)

"Order in Chaos, Path in Intelligence."

Agentao is a Governed Agent Runtime — a local-first, private-first, embeddable agent harness for Python hosts. Permissions, protocols, memory, plugins, and multi-session control are all first-class.

中文版本 README.zh.md

📚 Documentation — read this first

The full handbook lives in developer-guide/ (VitePress, bilingual). Production site: agentao.cn.

Audience	Read	Site
Coding agents — Claude Code / Codex / … embedding Agentao into another project	`docs/guides/embed-for-agents.md` (distilled, copy-paste playbook)	—
CLI users — driving `agentao` in the terminal	`developer-guide/en/cli/` (12 chapters: slash commands · plan mode · memory · replay · …)	agentao.cn/en/cli/
Embedding developers — building Agentao into your app	`developer-guide/en/` (Parts 1–7 + Appendix)	agentao.cn
中文	`developer-guide/zh/cli/` · `developer-guide/zh/`	agentao.cn/zh/cli/ · agentao.cn/zh/

Browse locally:

cd developer-guide && npx vitepress dev

For schema-level reference (every config file, every env var, every public API), the canonical doc is docs/reference/configuration.md. Everything else is in the Developer Guide.

Embed in 30 lines

pip install agentao

from pathlib import Path
from agentao import Agentao
from agentao.llm import LLMClient
from agentao.transport import NullTransport

agent = Agentao(
    working_directory=Path("/tmp/agent-run-1"),
    llm_client=LLMClient(
        api_key="sk-...",
        base_url="https://api.openai.com/v1",
        model="gpt-5.4",
    ),
    transport=NullTransport(),
)
reply = agent.chat("Summarize today's logs.")
print(reply)
agent.close()

This constructs an agent with no env-discovery, no implicit network, no global state — the host owns every input. For env-driven discovery (the path the CLI uses), call agentao.embedding.build_from_environment(working_directory=...) instead.

Embedding details: Developer Guide · Part 2 (Lifecycle) and Part 4 (Host Contract).

Coding agent (Claude Code, Codex, …) tasked with embedding Agentao into another project? Read docs/guides/embed-for-agents.md — a distilled, copy-paste integration playbook with construction skeletons, import rules, and a checklist.

CLI Quickstart

pip install 'agentao[cli]'

# .env in your project (all three are required):
printf "OPENAI_API_KEY=sk-your-key\nOPENAI_BASE_URL=https://api.openai.com/v1\nOPENAI_MODEL=gpt-5.4\n" > .env

# Smoke test — non-interactive
agentao -p "Reply with the single word: OK"

# Interactive REPL
agentao

Upgrading from 0.4.x? 0.5.0 removes what 0.4.x deprecated — agentao.harness (use agentao.host), agentao.session (use agentao.embedding.sessions) and the eight callback kwargs on Agentao(...) (use transport=, or build_compat_transport) — and two things that never warned: project_root is required on the session functions, and Agentao(...) takes only its first five parameters positionally. See docs/migration/0.4.x-to-0.5.0.md.

Upgrading from 0.3.x? From 0.4.0 the CLI deps moved into the [cli] extra. Use pip install 'agentao[full]' for zero behaviour change. See docs/migration/0.3.x-to-0.4.0.md.

First commands once the REPL is up:

/help       Every slash command + tools the agent has
/status     Model, mode, tokens, active skills
/model      Switch model on the current provider
/mode       Switch permission mode (read-only · workspace-write · full-access · plan)
/plan       Enter plan mode (read-only thinking with .agentao/plan.md)
/memory     Inspect persistent memory
/mcp list   MCP server status
/exit       Leave cleanly (don't Ctrl+C)

CLI handbook: agentao.cn/en/cli/ — 12 chapters covering every slash command and the mental model behind them.

Why Agentao?

The name encodes the design: Agent (capability) + Tao (governance). Three pillars of a governed runtime:

Pillar	What it means	How Agentao implements it
Constraint (约束)	Agents must not act without consent	Tool confirmation · permission modes (`read-only` / `workspace-write` / `full-access` / `plan`) · macOS `sandbox-exec`
Connectivity (连接)	Agents must reach the world beyond training	MCP (stdio / Streamable HTTP / SSE) · ACP (full-agent JSON-RPC) · plugins · hooks
Observability (可观测性)	Agents must show their work	Live thinking display · streaming tool output · full LLM logging · JSONL replay

Feature Overview

Area	What you get	Deep dive
Governance	Tool confirmation, four permission modes, plan mode, macOS sandbox	CLI ch. 3 · ch. 4
Context	Token tracking, LLM-summarized compaction, overflow recovery, file re-injection	CLI ch. 7
Memory	SQLite-backed persistent memory with two scopes (user / project), automatic recall, jieba 中文 segmentation	CLI ch. 6
Skills	Auto-discovered from `skills/`, GitHub-installable (`agentao skill install owner/repo[:path][@ref]`), plus `/crystallize` workflow	CLI ch. 5
Protocols	MCP (stdio / Streamable HTTP / SSE) for tools · ACP (stdio JSON-RPC) for full agents · plugin lifecycle	CLI ch. 8
Sub-agents	Built-in `codebase-investigator` / `generalist` · custom `.agentao/agents/<name>.md` · foreground/background dashboard	CLI ch. 11
Replay & Output	JSONL session recordings under `.agentao/replays/` · markdown-toggle · `/copy` last reply	CLI ch. 9
Embedding	`Agentao(...)` constructor · `events()` stream · `active_permissions()` · capability injection · ACP Pydantic schemas	DG Part 2 · Part 4

Installation

# Embedding host (Python `from agentao import Agentao`) — smallest closure
pip install agentao

# CLI user (`agentao` console script) — adds rich/prompt-toolkit/readchar/pygments
pip install 'agentao[cli]'

# Zero-behaviour-change upgrade from 0.3.x — full closure
pip install 'agentao[full]'

Required Python: 3.10+. Required env: OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL — all three, or startup raises ValueError.

For Anthropic / Gemini / DeepSeek / any OpenAI-compatible provider, set <NAME>_API_KEY + <NAME>_BASE_URL + <NAME>_MODEL and pick it via LLM_PROVIDER or /provider at runtime. To talk to Anthropic's own API natively (Messages API — working prompt caching, signed thinking), add <NAME>_API_FORMAT=anthropic-messages; for OpenAI's Responses API (a reasoning model's reasoning kept across requests), <NAME>_API_FORMAT=openai-responses. It is never inferred from a URL or a name. Full list: docs/reference/configuration.md.

For contributors

git clone https://github.com/jin-bo/agentao
cd agentao
uv sync
cp .env.example .env

# Run the CLI from source
uv run agentao
# or
./run.sh

# Tests
uv run python -m pytest tests/

Contributor entry points:

What	Where
Project layout, code conventions	`CLAUDE.md`
Adding a tool / agent / skill	Developer Guide · Part 5
Plugin author guide	Developer Guide · §5.7
Embedding contract & ACP schemas	Developer Guide · Part 4
Examples (skills · personas · integration blueprints)	`examples/`

Design Principles

Minimalism (极简) — pip install agentao and you're running. No databases, no cloud dependencies.
Transparency (透明) — Reasoning chain on screen in real time. Every LLM call and tool call logged to agentao.log.
Integrity (完整) — Context never silently dropped: LLM-summarized compaction, automatic memory recall, conversation continuity across restarts.

Etymology

Agentao = Agent + Tao (道) — the natural order that underlies all things. Three intertwined meanings:

Laws (法则) — rules that constrain and shape behavior
Methods (方法) — paths and techniques for accomplishing goals
Paths (路径) — routes through which things flow and connect

An agent without Tao is powerful but unpredictable. Agentao is the structure that makes that power trustworthy.

License

Open source. Use and modify as needed.

Acknowledgments

LLM clients: OpenAI Python SDK · Anthropic Python SDK
CLI: Rich · prompt_toolkit · readchar
Optional local JS rendering for web_fetch: Playwright
MCP: Model Context Protocol SDK — architecture inspired by Gemini CLI
Inspired by Claude Code

agentao

Links

README