一个极简、模块化的 agent 控制平面。Gateway first，event first，module first。
AgentCore 是面向单用户的 agent 控制平面。Gateway 是长期运行的后台进程，也是 sessions、state、events、modules 和 connected clients 的事实来源。CLI、WebUI、scripts 和其他客户端只是 gateway API 的消费者。
English: AgentCore is a single-user agent control plane. The gateway is the long-lived backend process and the source of truth for sessions, state, events, modules, and connected clients. CLI, WebUI, scripts, and other clients are gateway API consumers.
本仓库目前处于设计 + MVP 骨架阶段。第一目标不是做一个庞大的个人助手产品，而是定义一套小型 runtime 与 gateway contract，让个人助手、coding agent、automation agent、research agent 都能在其上实现，同时不强迫任何一种产品形态或协作范式。
当前第一条纵切已经可以编译和启动：
WebUI / CLI / WS / HTTP RPC
-> gateway
-> core lane + run state
-> native runtime
-> dummy scripted provider
-> optional tool executor
-> event log
默认 WebUI 与 WS/HTTP gateway 端口是 14514。
当前命名约定：
agentcore-extension-api是 Rust native 模块在同一进程内实现的 trait，例如LlmProvider、AgentRuntimeHarness、ToolExecutor。agentcore-abi是 native/WASM 模块都要声明和协商的稳定边界，例如 module manifest、capability 和 ABI version。- 简单说：Extension API 是“模块怎么被 Rust 调用”，ABI 是“模块怎么被 Gateway 安全识别和授权”。
当前检出了两个上游项目作为设计参考：
| 项目 | 本地路径 | 上游 commit | License |
|---|---|---|---|
| OpenClaw | references/upstreams/openclaw |
8256b747bec6f14297c4f511e5f80e115434d650 |
MIT |
| Hermes Agent | references/upstreams/hermes-agent |
629d8b843d8d8507925fd35344f57de776cb1490 |
MIT |
AgentCore 借鉴架构模式，不复制实现代码。未来如果复制或派生任何实现，必须保留 license notices，并单独记录设计决策。
- 中文主索引: docs/README.md
- English index: docs/en/README.md
- 可视化导航: docs/agentcore-design-map.html
- 如果只想快速建立全局图，先读中文主索引里的 扩展架构速读 或英文镜像里的 The Extension Architecture Brief。
- Core 只运行 agent steps 并调度 work。它不知道 HTTP、WebSocket、SQLite、Postgres、OpenAI、Anthropic、Docker 或 WebUI。
- Gateway 拥有持久 runtime state。客户端不直接运行 agents。
- 每个状态变化都是 event。Storage backends 持久化 events 和派生索引。
- LLM providers、transports、persistence、tools、sandboxing、WebUI、learning 和 orchestrators 都是 modules。
- 默认发行版可以附带官方模块，但 core crate 必须在没有这些模块时仍可使用。
- Sandboxing 是 tool execution policy，不是 core runtime policy。
- Replay 默认是确定性的：replay 读取记录下来的 model/tool outputs。重新执行是独立的
rerun或fork。 - 多 agent 协作必须经过 gateway，但 AgentCore 不规定协作范式。平台只提供 queue/instant communication、sessions、runs、events、artifacts、gates 和 module hooks；supervisor、subagent、handoff、group chat、swarm、remote-agent 等模式由 modules 或 tools 实现。
agentcore/
crates/
agentcore-events/
agentcore-core/
agentcore-abi/
agentcore-extension-api/
agentcore-gateway/
agentcore-protocol/
agentcore-wasm-host/
agentcore-pkg/
agentcore-cli/
modules/
transport-http/
transport-ws/
transport-acp/
webui/
persistence-sqlite/
persistence-postgres/
llm-dummy/
llm-openai/
llm-openai-compatible/
llm-anthropic/
llm-ollama/
llm-openrouter/
agent-runtime-native/
agent-runtime-acp-bridge/
executor-local/
executor-docker/
executor-remote/
comms-queue/
comms-instant/
memory-core/
memory-sqlite/
memory-dreaming/
skill-store-fs/
skill-loader/
skill-manager/
skill-curator/
learning-review/
policy-approval/
observability-basic/
orchestrator-sequential/
wit/
agentcore.wit
docs/
examples/
tests/
references/upstreams/
第一个可工作的版本是一个闭环：
start gateway
create agent
submit session input
scheduler accepts run
LLM provider returns response
optional tool call executes
events persist
client subscribes to events
session can replay from event log
MVP 应先使用 llm-dummy、executor-local、persistence-sqlite 和 transport-http，再加入真实 providers、WebUI 或 WASM package distribution。
cargo fmt --all
cargo check --workspace --all-targets
cargo test --workspace --all-targets运行当前 MVP：
cargo run -p agentcore-cli -- serve
cargo run -p agentcore-cli -- run -q "hello"
cargo run -p agentcore-cli -- tool dummy.lookup --query "gateway"然后打开：
http://127.0.0.1:14514
严格检查：
cargo clippy --workspace --all-targets -- -D warnings可选编译裁剪：
cargo check -p agentcore-cli --no-default-features
cargo check -p agentcore-cli --features providers-official
cargo check -p agentcore-cli --features browser-tools