Skip to content
Back to search

agentao

Local-first, governed AI agent runtime for Python — embed it in your app, or run it as a CLI or ACP server. Permissions, MCP, memory and audit replay built in.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/jin-bo/agentao with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/jin-bo/agentao'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jin-bo--agentao/badge.svg)](/listings/jin-bo--agentao)

HTML

<a href="/listings/jin-bo--agentao"><img src="/api/listings/jin-bo--agentao/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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:

/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/)** — 12 chapters covering every slash command and the mental model behind them.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 216 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Agentao (Agent + Tao)
  2. ```
  3. ___ _
  4. / _ \ ___ _ ___ ___ ___| |_ ___ ___
  5. / _ // _` / -_)| _ \/ _ \ _|/ _` / _ \
  6. /_/ |_| \__, \___||_// \___/\__|\__,_\___/
  7. |___/ (The Way of Agents)
  8. ```
  9. > **"Order in Chaos, Path in Intelligence."**
  10. >
  11. > **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.
  12. [中文版本 README.zh.md](README.zh.md)
  13. ---
  14. ## 📚 Documentation — read this first
  15. The full handbook lives in `developer-guide/` (VitePress, bilingual). Production site: **[agentao.cn](https://agentao.cn)**.
  16. | Audience | Read | Site |
  17. |---|---|---|
  18. | **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) | — |
  19. | **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/) |
  20. | **Embedding developers** — building Agentao into your app | [`developer-guide/en/`](developer-guide/en/) (Parts 1–7 + Appendix) | [agentao.cn](https://agentao.cn) |
  21. | **中文** | [`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/) |
  22. Browse locally:
  23. ```bash
  24. cd developer-guide && npx vitepress dev
  25. ```
  26. 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.
  27. ---
  28. ## Embed in 30 lines
  29. ```bash
  30. pip install agentao
  31. ```
  32. ```python
  33. from pathlib import Path
  34. from agentao import Agentao
  35. from agentao.llm import LLMClient
  36. from agentao.transport import NullTransport
  37. with Agentao(
  38. working_directory=Path("/tmp/agent-run-1"),
  39. llm_client=LLMClient(
  40. api_key="sk-...",
  41. base_url="https://api.openai.com/v1",
  42. model="gpt-5.4",
  43. ),
  44. transport=NullTransport(),
  45. ) as agent:
  46. reply = agent.chat("Summarize today's logs.")
  47. print(reply)
  48. ```
  49. 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.
  50. 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).
  51. > **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.
  52. ---
  53. ## CLI Quickstart
  54. ```bash
  55. pip install 'agentao[cli]'
  56. # .env in your project (all three are required):
  57. printf "OPENAI_API_KEY=sk-your-key\nOPENAI_BASE_URL=https://api.openai.com/v1\nOPENAI_MODEL=gpt-5.4\n" > .env
  58. # Smoke test — non-interactive
  59. agentao -p "Reply with the single word: OK"
  60. # Interactive REPL
  61. agentao
  62. ```
  63. > **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).
  64. >
  65. > **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).
  66. First commands once the REPL is up:
  67. ```text
  68. /help Every slash command + tools the agent has
  69. /status Model, mode, tokens, active skills
  70. /model Switch model on the current provider
  71. /mode Switch permission mode (read-only · workspace-write · full-access · plan)
  72. /plan Enter plan mode (read-only thinking with .agentao/plan.md)
  73. /memory Inspect persistent memory
  74. /mcp list MCP server status
  75. /exit Leave cleanly (don't Ctrl+C)
  76. ```
  77. CLI handbook: **[agentao.cn/en/cli/](https://agentao.cn/en/cli/)** — 13 chapters covering every slash command and the mental model behind them.
  78. ---
  79. ## Why Agentao?
  80. The name encodes the design: *Agent* (capability) + *Tao* (governance). Three pillars of a governed runtime:
  81. | Pillar | What it means | How Agentao implements it |
  82. |---|---|---|
  83. | **Constraint** (约束) | Agents must not act without consent | Tool confirmation · permission modes (`read-only` / `workspace-write` / `full-access` / `plan`) · macOS `sandbox-exec` |
  84. | **Connectivity** (连接) | Agents must reach the world beyond training | MCP (stdio / Streamable HTTP / SSE) · ACP (full-agent JSON-RPC) · plugins · hooks |
  85. | **Observability** (可观测性) | Agents must show their work | Live thinking display · streaming tool output · full LLM logging · JSONL replay |
  86. 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)**.
  87. ---
  88. ## Feature Overview
  89. | Area | What you get | Deep dive |
  90. |---|---|---|
  91. | **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) |
  92. | **Context** | Token tracking, LLM-summarized compaction, overflow recovery, file re-injection | [CLI ch. 7](developer-guide/en/cli/7-context-status.md) |
  93. | **Memory** | SQLite-backed persistent memory with two scopes (user / project), automatic recall, jieba 中文 segmentation | [CLI ch. 6](developer-guide/en/cli/6-memory.md) |
  94. | **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) |
  95. | **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) |
  96. | **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) |
  97. | **Replay & Output** | JSONL session recordings under `.agentao/replays/` · markdown-toggle · `/copy` last reply | [CLI ch. 9](developer-guide/en/cli/9-replay-output.md) |
  98. | **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/) |
  99. ---
  100. ## Installation
  101. ```bash
  102. # Embedding host (Python `from agentao import Agentao`) — smallest closure
  103. pip install agentao
  104. # CLI user (`agentao` console script) — adds rich/prompt-toolkit/readchar/pygments
  105. pip install 'agentao[cli]'
  106. # Zero-behaviour-change upgrade from 0.3.x — full closure
  107. pip install 'agentao[full]'
  108. ```
  109. **Required Python:** 3.10+. **Required env:** `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `OPENAI_MODEL` — all three, or startup raises `ValueError`.
  110. 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).
  111. ---
  112. ## For contributors
  113. ```bash
  114. git clone https://github.com/jin-bo/agentao
  115. cd agentao
  116. uv sync
  117. cp .env.example .env
  118. # Run the CLI from source
  119. uv run agentao
  120. # or
  121. ./run.sh
  122. # Tests
  123. uv run python -m pytest tests/
  124. ```
  125. Contributor entry points:
  126. | What | Where |
  127. |---|---|
  128. | Project layout, code conventions | [`CLAUDE.md`](CLAUDE.md) |
  129. | Adding a tool / agent / skill | [Developer Guide · Part 5](https://agentao.cn/en/part-5/) |
  130. | Plugin author guide | [Developer Guide · §5.7](https://agentao.cn/en/part-5/7-plugin-hooks) |
  131. | Embedding contract & ACP schemas | [Developer Guide · Part 4](https://agentao.cn/en/part-4/) |
  132. | Examples (skills · personas · integration blueprints) | [`examples/`](examples/) |
  133. ---
  134. ## Design Principles
  135. 1. **Minimalism (极简)** — `pip install agentao` and you're running. No databases, no cloud dependencies.
  136. 2. **Transparency (透明)** — Reasoning chain on screen in real time. Every LLM call and tool call logged to `agentao.log`.
  137. 3. **Integrity (完整)** — Context never silently dropped: LLM-summarized compaction, automatic memory recall, conversation continuity across restarts.
  138. ---
  139. ## Etymology
  140. **Agentao** = *Agent* + *Tao* (道) — the natural order that underlies all things. Three intertwined meanings:
  141. - **Laws (法则)** — rules that constrain and shape behavior
  142. - **Methods (方法)** — paths and techniques for accomplishing goals
  143. - **Paths (路径)** — routes through which things flow and connect
  144. An agent without Tao is powerful but unpredictable. *Agentao* is the structure that makes that power trustworthy.
  145. ---
  146. ## License
  147. Open source. Use and modify as needed.
  148. ## Acknowledgments
  149. - LLM clients: [OpenAI Python SDK](https://github.com/openai/openai-python) · [Anthropic Python SDK](https://github.com/anthropics/anthropic-sdk-python)
  150. - CLI: [Rich](https://github.com/Textualize/rich) · [prompt_toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) · [readchar](https://github.com/magmax/python-readchar)
  151. - Optional local JS rendering for `web_fetch`: [Playwright](https://github.com/microsoft/playwright-python)
  152. - MCP: [Model Context Protocol SDK](https://github.com/modelcontextprotocol/python-sdk) — architecture inspired by [Gemini CLI](https://github.com/google-gemini/gemini-cli)
  153. - Inspired by [Claude Code](https://github.com/anthropics/claude-code)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.