# 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](README.zh.md)

---

## 📚 Documentation — read this first

The full handbook lives in `developer-guide/` (VitePress, bilingual). Production site: **[agentao.cn](https://agentao.cn)**.

| Audience | Read | Site |
|---|---|---|
| **Coding agents** — Claude Code / Codex / … embedding Agentao into another project | [`docs/guides/embed-for-agents.md`](docs/guides/embed-for-agents.md) (distilled, copy-paste playbook) | — |
| **CLI users** — driving `agentao` in the terminal | [`developer-guide/en/cli/`](developer-guide/en/cli/) (13 chapters: slash commands · plan mode · memory · replay · …) | [agentao.cn/en/cli/](https://agentao.cn/en/cli/) |
| **Embedding developers** — building Agentao into your app | [`developer-guide/en/`](developer-guide/en/) (Parts 1–7 + Appendix) | [agentao.cn](https://agentao.cn) |
| **中文** | [`developer-guide/zh/cli/`](developer-guide/zh/cli/) · [`developer-guide/zh/`](developer-guide/zh/) | [agentao.cn/zh/cli/](https://agentao.cn/zh/cli/) · [agentao.cn/zh/](https://agentao.cn/zh/) |

Browse locally:

```bash
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`](docs/reference/configuration.md). Everything else is in the Developer Guide.

---

## Embed in 30 lines

```bash
pip install agentao
```

```python
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)](https://agentao.cn/en/part-2/) and [Part 4 (Host Contract)](https://agentao.cn/en/part-4/7-host-contract).

> **Coding agent** (Claude Code, Codex, …) tasked with embedding Agentao into another project? Read [`docs/guides/embed-for-agents.md`](docs/guides/embed-for-agents.md) — a distilled, copy-paste integration playbook with construction skeletons, import rules, and a checklist.

---

## CLI Quickstart

```bash
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](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](docs/migration/0.3.x-to-0.4.0.md).

First commands once the REPL is up:

```text
/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/](https://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:

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

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](https://agentao.cn/en/part-1/6-compared-to-vendor-sdks)**.

---

## Feature Overview

| Area | What you get | Deep dive |
|---|---|---|
| **Governance** | Tool confirmation, four permission modes, plan mode, macOS sandbox | [CLI ch. 3](developer-guide/en/cli/3-permissions-modes.md) · [ch. 4](developer-guide/en/cli/4-plan-mode.md) |
| **Context** | Token tracking, LLM-summarized compaction, overflow recovery, file re-injection | [CLI ch. 7](developer-guide/en/cli/7-context-status.md) |
| **Memory** | SQLite-backed persistent memory with two scopes (user / project), automatic recall, jieba 中文 segmentation | [CLI ch. 6](developer-guide/en/cli/6-memory.md) |
| **Skills** | Auto-discovered from `skills/`, GitHub-installable (`agentao skill install owner/repo[:path][@ref]`), plus `/crystallize` workflow | [CLI ch. 5](developer-guide/en/cli/5-skills-crystallize.md) |
| **Protocols** | MCP (stdio / Streamable HTTP / SSE) for tools · ACP (stdio JSON-RPC) for full agents · plugin lifecycle | [CLI ch. 8](developer-guide/en/cli/8-mcp-acp-plugins.md) |
| **Sub-agents** | Built-in `codebase-investigator` / `generalist` · custom `.agentao/agents/<name>.md` · foreground/background dashboard | [CLI ch. 11](developer-guide/en/cli/11-sessions-agents.md) |
| **Replay & Output** | JSONL session recordings under `.agentao/replays/` · markdown-toggle · `/copy` last reply | [CLI ch. 9](developer-guide/en/cli/9-replay-output.md) |
| **Embedding** | `Agentao(...)` constructor · `events()` stream · `active_permissions()` · capability injection · ACP Pydantic schemas | [DG Part 2](https://agentao.cn/en/part-2/) · [Part 4](https://agentao.cn/en/part-4/) |

---

## Installation

```bash
# 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`](docs/reference/configuration.md).

---

## For contributors

```bash
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`](CLAUDE.md) |
| Adding a tool / agent / skill | [Developer Guide · Part 5](https://agentao.cn/en/part-5/) |
| Plugin author guide | [Developer Guide · §5.7](https://agentao.cn/en/part-5/7-plugin-hooks) |
| Embedding contract & ACP schemas | [Developer Guide · Part 4](https://agentao.cn/en/part-4/) |
| Examples (skills · personas · integration blueprints) | [`examples/`](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](https://github.com/openai/openai-python) · [Anthropic Python SDK](https://github.com/anthropics/anthropic-sdk-python)
- CLI: [Rich](https://github.com/Textualize/rich) · [prompt_toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) · [readchar](https://github.com/magmax/python-readchar)
- Optional local JS rendering for `web_fetch`: [Playwright](https://github.com/microsoft/playwright-python)
- MCP: [Model Context Protocol SDK](https://github.com/modelcontextprotocol/python-sdk) — architecture inspired by [Gemini CLI](https://github.com/google-gemini/gemini-cli)
- Inspired by [Claude Code](https://github.com/anthropics/claude-code)