Agentao

What is Agentao about?

Agentao delivers a governed agent runtime that runs locally in a Python host. It isolates every input, enforces permission modes, tracks context, persists memory in SQLite, and records full session replays. The design follows three pillars – constraint, connectivity, and observability – to make powerful agents trustworthy.

How to use Agentao?

Embedding

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()

CLI

pip install 'agentao[cli]'
# create .env with required variables
printf "OPENAI_API_KEY=sk-your-key\nOPENAI_BASE_URL=https://api.openai.com/v1\nOPENAI_MODEL=gpt-5.4\n" > .env

# quick test
agentao -p "Reply with the single word: OK"

# interactive REPL
agentao

Use slash commands such as /help, /status, /model, /mode, /memory, /mcp list, etc., to control the session.

Key features of Agentao

• Governance: Four permission modes, tool confirmation, plan mode, macOS sandbox‑exec.
• Context management: Token tracking, LLM‑summarized compaction, overflow recovery, file re‑injection.
• Persistent memory: SQLite‑backed, user‑ and project‑scoped, automatic recall, Chinese segmentation.
• Skill system: Auto‑discovery from skills/, GitHub‑installable, crystallization workflow.
• Protocols: MCP (stdio / HTTP / SSE) for tool calls, ACP (JSON‑RPC) for full agents, plugin lifecycle hooks.
• Sub‑agents: Built‑in codebase investigator, generalist, and custom markdown‑defined agents.
• Replay & audit: JSONL session recordings, markdown toggles, /copy command.
• Embedding API: Constructor‑based creation, event streams, active permission queries, ACP Pydantic schemas.

Use cases of Agentao

• Coding assistants: Embed Agentao in IDE extensions or custom scripts to let LLMs edit code with strict permission checks.
• CLI‑driven automation: Run repetitive tasks (log analysis, data extraction) from the terminal with reproducible replay logs.
• Enterprise governance: Enforce read‑only or write‑approved modes for AI agents accessing proprietary codebases or confidential documents.
• Multi‑session orchestration: Launch background sub‑agents for codebase investigation while the main agent focuses on user interaction.
• Skill marketplace: Distribute and install community‑created skills via GitHub, extending functionality without altering core code.

FAQ from Agentao

Q: Do I need an internet connection? A: Only if the selected LLM provider requires it. The runtime itself has no implicit network calls; you control all transport via LLMClient and Transport objects.

Q: Which LLM providers are supported? A: Any OpenAI‑compatible provider (OpenAI, Anthropic, Gemini, DeepSeek, etc.) by setting <NAME>_API_KEY, <NAME>_BASE_URL, and <NAME>_MODEL. The provider is selected via LLM_PROVIDER or the /provider command.

Q: How is memory persisted? A: In a SQLite database under the working directory, separated into user‑level and project‑level scopes.

Q: Can I run Agentao as a server for other applications? A: Yes, via the MCP/ACP protocols (stdio, Streamable HTTP, or SSE). The CLI’s /mcp list shows active server endpoints.

Q: What changed in the 0.5.0 upgrade? A: Deprecated agentao.harness and agentao.session, revamped constructor signature, and moved CLI dependencies into the [cli] extra. See the migration docs for details.

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

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