agentao

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

with 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(),
) as agent:
    reply = agent.chat("Summarize today's logs.")
    print(reply)

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/ — 13 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:

How this compares with the Claude Agent SDK, the OpenAI Agents SDK and Strands — and when one of those is the better fit: Compared with Vendor SDKs.

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

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