agentao 0.4.11

A governed agent runtime for local-first, private-first, embeddable AI agents.

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.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 / 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 / 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

1. Minimalism (极简) — pip install agentao and you're running. No databases, no cloud dependencies.
2. Transparency (透明) — Reasoning chain on screen in real time. Every LLM call and tool call logged to agentao.log.
3. 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 web fetch: Crawl4AI
• MCP: Model Context Protocol SDK — architecture inspired by Gemini CLI
• Inspired by Claude Code