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.
📚 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.3.x? From 0.4.0 the CLI deps moved into the
[cli]extra. Usepip 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. 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 agentaoand 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 client: OpenAI 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
1 maintainer
Release files for agentao 0.4.27
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| agentao-0.4.27.tar.gz | 1.2 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agentao-0.4.27-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.4 MB
Release files / agentao-0.4.27.tar.gz
| Download URL | agentao-0.4.27.tar.gz |
|---|---|
| Size | 1.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d707ae15127efb87f474650475c3e79e103431de3626f8c13fddf88ae9bda03b
|
|
BLAKE2b-256 checksum How to use checksums |
f7a0da3e8787f10a25689382505c865664a0d1b1f2316993b06cac91c3dbda25
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / agentao-0.4.27-py3-none-any.whl
| Download URL | agentao-0.4.27-py3-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a54bdee8c027e7ed0642bf21e8194e19211dd5c32abe52e28b1a5a57653aae9a
|
|
BLAKE2b-256 checksum How to use checksums |
5829e1277b4cd654c4423ce8e8a15b56a8e26d11a93229edd64c62602d5a0fed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency log
