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.

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:

Feature Overview

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:

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 local JS rendering for web_fetch: Playwright
• MCP: Model Context Protocol SDK — architecture inspired by Gemini CLI
• Inspired by Claude Code