给业务程序接入 agent，通常很快会从“能不能调一次模型”变成更难的工程问题：谁拥有 API 配置，工具调用要不要确认，session 如何在重启后继续，怎样把一段失败的工作流还原出来，以及 CLI 和嵌入式 SDK 会不会演化成两套不兼容的行为。只把一个聊天循环塞进 Python 并不能解决这些边界；但一开始就接入托管平台，又常常意味着把运行状态和数据治理一并交出去。

今天看的是 jin-bo/agentao。它把自己定位为 Python host 可嵌入、local-first 的“governed agent runtime”：既能用 Agentao(...) 放进自己的应用，也能作为终端 CLI 或 ACP server 运行。权限确认与四种 mode、MCP/ACP、SQLite-backed persistent memory、skills、sub-agents、多 session 控制，以及 JSONL session replay 都放在同一个 runtime 里，而不是让应用各自拼装。

按 GitHub 仓库页、README、LICENSE、main 分支与 Releases 页面在 2026-09-18 10:05 Asia/Shanghai 可核验的信息，jin-bo/agentao 有 303 stars、11 forks，主要语言为 Python，license 是 MIT。仓库创建于 2026-02-10 01:30:42 UTC；main 最新 push/HEAD 为 a2c8c6d，时间 2026-09-18 09:42:00 UTC，内容开始准备 0.5.0 的移除项。最新 GitHub Release 是 v0.4.27，发布于 2026-09-18 09:18:41 UTC。也就是说 main 已领先于最新稳定 release，生产接入应优先 pin release，而不是直接追 main。

项目概览

属性详情
仓库jin-bo/agentao
定位可嵌入、local-first 的 Python governed agent runtime
Stars / Forks303 / 11
主要语言Python
许可证MIT
创建时间2026-02-10 01:30:42 UTC
Latest push / main HEAD2026-09-18 09:42:00 UTC / a2c8c6d
最新 Releasev0.4.27，2026-09-18 09:18:41 UTC
协议与记录MCP（stdio / Streamable HTTP / SSE）、ACP、JSONL replay

有价值的地方是把 host contract 说清楚

README 里的最小嵌入方式是 pip install agentao，再显式构造 Agentao、LLMClient 和 transport。它特别强调这个路径没有环境变量发现、隐式网络或全局状态：working directory、模型 client 与 transport 都由 host 提供。对已经有 Web 服务、队列消费者或桌面应用的团队，这个边界比“自动读环境然后自己启动”更好管理——凭据来源、网络出口和生命周期都仍在应用手里。

另一侧，agentao[cli] 给需要终端入口的人同一套 runtime。CLI 的 /mode 可切换 read-only、workspace-write、full-access、plan；/plan 把只读计划写到 .agentao/plan.md，/memory 查看持久 memory，/mcp list 检查 server 状态。它并没有把嵌入和 CLI 做成两种产品，而是让两者共享 permissions、protocols 和 session 语义。

把治理能力放在工具调用前面

Agentao 的“governed”并不只是一个标签。README 将 tool confirmation、四种 permission mode 和 macOS sandbox-exec 放入 constraint 一层；连接层支持 MCP 的 stdio、Streamable HTTP、SSE，以及作为完整 agent JSON-RPC 的 ACP；可观测一层则有 streaming tool output、LLM logging 与 .agentao/replays/ 下的 JSONL replay。对需要复盘“agent 为什么改了这个文件”的开发流程来说，回放至少让事件记录有一个确定的落点。

它的 memory 也没有被描述成黑盒云服务：README 写的是 SQLite-backed、user/project 两个 scope 的持久 memory 与自动 recall。skills 可从 skills/ 自动发现，也可按 owner/repo[:path][@ref] 从 GitHub 安装；sub-agent 则有内建角色及 .agentao/agents/ 自定义入口。这些功能适合希望自己掌握文件布局和存储位置的 Python 应用，但也意味着你需要自己确定 retention、备份与团队共享策略。

先从最小权限的真实任务开始

项目要求 Python 3.10+。README 示例的 CLI 配置需要 API key、base URL 与 model 三项；也列出通过相应环境变量接入 Anthropic、Gemini、DeepSeek 或其他 OpenAI-compatible provider 的路径。一个比较稳妥的试用顺序是：在非生产工作目录中先用 read-only 或 plan mode 跑一个明确任务，确认 tool confirmation、日志和 replay 中到底记录哪些内容；再给一个隔离 workspace 开 workspace-write，最后才考虑 full-access 或远端 MCP。

这里要格外注意，permission mode、确认提示和 replay 并不自动构成完整的数据隔离。agent 的 prompt、tool output、路径和 session metadata 是否会进入日志或 memory，仍要按你自己的数据分级来验证；macOS sandbox 也不等于跨平台的安全边界。尤其最新 main 已在为 0.5.0 移除旧 API 做准备，嵌入式调用方应固定依赖版本、跑自己的 integration tests，并在升级前读 migration 文档。

总结

jin-bo/agentao 值得试的原因，不是它又把 MCP、memory 和 sub-agent 都列了一遍，而是它尝试把这些能力放进一个 Python host 仍能掌握的 contract 里：应用自己提供 client 与 transport，运行时负责权限模式、协议接入、会话记录和回放。若你在做一个需要 agent 能力、但不想把执行权和可观测性完全外包的 Python 工具，可以先用嵌入式最小闭包加只读 mode 试一个真实工作流，再决定要不要扩大工具权限和持久化范围。

项目地址：https://github.com/jin-bo/agentao diff —git a/src/content/posts/ja/2026-09-18-agentao-governed-python-agent-runtime.md b/src/content/posts/ja/2026-09-18-agentao-governed-python-agent-runtime.md new file mode 100644 index 0000000..6b124c2 --- /dev/null +++ b/src/content/posts/ja/2026-09-18-agentao-governed-python-agent-runtime.md @@ -0,0 +1,61 @@

title: “Agentao：Python Agent に、埋め込み・replay・permission boundary を備えた local runtime を与える” description: “jin-bo/agentao は MIT license の Python project。埋め込み可能な agent harness、CLI、MCP/ACP、permission mode、SQLite memory、JSONL replay を一つの local-first runtime にまとめる。” pubDate: 2026-09-18 10:00:00 tags: [“github”, “ai-coding”, “agent-runtime”, “python”, “mcp”, “acp”, “local-first”, “security”]