AG Core

AG Core 是一个用于构建 AI 智能体（Agent）的 Rust 工具箱，提供 LLM 调用、提示词工程、工具系统、记忆检索、Agent 运行时等核心能力，所有模块通过 trait 抽象、可插拔、可离线测试。

这是什么？

AG Core 不是 Agent 产品，而是 Agent 的底层依赖库：上层应用（TUI / Bot 网关 / 业务服务）基于 AG Core 装配出符合自身场景的 Agent。设计原则：

• 模块化 —— 五大功能领域（LLM / Prompt / Tool / Memory / Agent）独立 crate-internal 模块，通过 trait 解耦
• 可插拔 —— LLM Provider、记忆存储、工具注册全部通过 trait 抽象，可替换为自有实现
• 可离线 —— 公开 MockProvider，所有示例与测试无需 API key 即可运行
• 异步优先 —— 所有 IO API 均为 async，基于 tokio 运行时

适合用来：

• 搭建支持多轮对话 + 工具调用的智能体服务
• 接入多家 LLM（OpenAI / Anthropic / DeepSeek / Qwen 等）
• 在 Agent 中组合提示词模板、知识检索、MCP 工具
• 在 Rust 中复用一套"业务无关"的 Agent 基础设施

快速上手

5 分钟上手，无需 API key（使用 MockProvider 预设响应）。

1. 添加依赖

[dependencies]
agcore = "0.3"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

2. 第一个 Agent

use std::sync::Arc;

use agcore::agent::{Agent, AgentBuilder, AgentSession};
use agcore::llm::hooks::HookExecutor;
use agcore::llm::mock::MockProvider;
use agcore::llm::LlmProvider;
use agcore::llm::types::message::{ContentBlock, Message};
use agcore::llm::types::response_v2::{MessageResponse, StopReason};
use agcore::llm::types::Usage;
use agcore::tools::ToolRegistry;

struct Greeter;

impl Agent for Greeter {
    fn name(&self) -> &str { "greeter" }
    fn system_prompt(&self) -> Option<&str> { Some("你是一个中文助手，回答简短。") }
}

fn text_response(text: &str) -> MessageResponse {
    MessageResponse {
        id: "r".into(),
        model: "mock".into(),
        message: Message::Assistant {
            content: vec![ContentBlock::Text { text: text.into() }],
        },
        usage: Usage::from_input_output(2, text.chars().count() as u32),
        stop_reason: StopReason::Stop,
        extra: Default::default(),
    }
}

#[tokio::main]
async fn main() {
    // 1. MockProvider：预设响应，无须 API key
    let provider: Arc<dyn LlmProvider> =
        Arc::new(MockProvider::new(vec![text_response("你好，我是 agcore。")]));

    // 2. 装配 RuntimeBundle（必填：provider / tool_registry / hook_executor）
    let bundle = Arc::new(
        AgentBuilder::new()
            .provider(provider)
            .tool_registry(Arc::new(ToolRegistry::new()))
            .hook_executor(Arc::new(HookExecutor::new()))
            .build()
            .expect("装配 RuntimeBundle 失败"),
    );

    // 3. 创建会话并提交首轮
    let agent: Arc<dyn Agent> = Arc::new(Greeter);
    let mut session = AgentSession::new(agent, "demo", bundle);
    let resp = session.submit_turn("你好").await.expect("submit_turn 失败");
    println!("LLM: {}", resp.text());
}

跑起来：

cargo run
# LLM: 你好，我是 agcore。

接真实 Provider（如 OpenAI）只需把 MockProvider 换成：

use agcore::llm::provider::{create_provider, ProviderConfig, ProviderType};

let provider = create_provider(
    ProviderType::OpenaiChat,
    ProviderConfig {
        base_url: "https://api.openai.com/v1".into(),
        api_key: std::env::var("OPENAI_API_KEY").expect("未设置 OPENAI_API_KEY"),
        model: "gpt-4o-mini".into(),
    },
).expect("创建 Provider 失败");

更多端到端示例见 examples/ 目录（共 18 个，全部可 cargo run --example <name>）：

示例	说明
quick_start	最短可运行示例：MockProvider + EchoTool + submit_turn，新用户 5 分钟上手
end_to_end	完整集成示例：3 工具 + 3 轮对话 + SqliteStore 持久化跨连接验证
agent_session_demo	Agent + 会话 + SessionMemory 完整链路（MockProvider 离线）
custom_tool	自定义工具注册、单次 / 并行调用、权限检查
prompt_composer	提示词模板与组合器（纯离线）
task_agent_demo	Plan 解析、Step 状态机、错误路径
conversation_memory_demo	对话记忆滑动窗口与隔离
knowledge_search_demo	知识页面关键词检索
streaming_events_demo	LLM 流式响应事件消费（含错误路径）
simple_visit	真实 LLM 调用（OpenAI / Anthropic，设置 OPENAI_* / ANTHROPIC_* 环境变量）
document_demo	文档分割：RecursiveCharacterSplitter 将长文本切分为可嵌入片段
knowledge_graph_demo	知识图谱：实体-关系 CRUD、BFS 遍历、关键词/标签检索
context_slot_demo	多上下文分区：ContextSlot 分区管理、FocusedConfig 聚焦策略
sub_agent_dispatch_demo	子任务分发：SubTask 异步执行与结果汇聚
dispatch_stream_demo	分发流式输出：SubTaskStreamEvent 实时消费
engine_demo	Agent 执行引擎：SessionManager 会话树 + Checkpointer 快照恢复
bridge_keys_demo	桥接键：Agent 间上下文键值透传
agent_switch_demo	Agent 热切换：会话中动态切换 Agent 角色

Feature 组合

AG Core 通过 Cargo features 让下游按需选择模块，跳过不需要的编译单元和重型依赖。default = ["full"] 保持向后兼容——不指定 features 时行为与 v0.3.0 一致。

快捷组合

组合	场景	包含的 features
full（default）	全栈使用，兼容 v0.3.0	全部 16 个 feature
light	生产常用，跳过 Anthropic/DeepSeek/Qwen/Ollama	llm + provider-openai + tools + tools-mcp + memory + agent + engine + prompt + document
chat	纯对话（跳过 SQLite 和 MCP）	agent + provider-openai
multi	多 Agent 复合（chat + subagent + switch + checkpointer）	engine + provider-openai

Cargo.toml 配置示例

# 默认全栈（兼容 v0.3.0）
[dependencies]
agcore = "0.3"

# 纯对话场景：跳过 SQLite 和 MCP，编译更快
[dependencies]
agcore = { version = "0.3", default-features = false, features = ["chat", "provider-openai"] }

# 生产常用：OpenAI + 工具 + 记忆 + Agent
[dependencies]
agcore = { version = "0.3", default-features = false, features = ["light"] }

# 多 Agent 复合 + MCP 工具
[dependencies]
agcore = { version = "0.3", default-features = false, features = ["multi", "provider-openai", "tools-mcp"] }

模块级 features

如需更细粒度控制，可单独启用模块级 features：

Feature	覆盖内容	imply
document	Document + RecursiveCharacterSplitter	—
llm-types	Message / ToolDef / Usage 等 IR 类型	—
prompt	PromptTemplate + PromptComposer	llm-types
llm	Provider trait + LlmCycle + hooks + compact + embedding + mock	llm-types
tools	BaseTool + ToolRegistry	llm-types
tools-mcp	McpClient（Stdio/StreamableHttp）	tools
memory	MemoryStore + Conversation + VectorStore + KnowledgeGraph + Retriever	document + llm
memory-sqlite	SqliteStore	memory
agent	Agent + Builder + Session + ContextSlot + Summary	llm + tools + memory
engine	SessionManager + Checkpointer + SubAgent + Switch	agent
provider-openai	OpenAI Provider 实现	llm
provider-anthropic	Anthropic Provider 实现	llm
provider-deepseek	DeepSeek Provider 实现	llm
provider-qwen	Qwen Provider 实现	llm
provider-ollama	Ollama Provider 实现	llm
tracing-init	init_tracing() 函数	—

升级指南（v0.3.0 → v0.3.2）

LlmProvider trait 路径变更

v0.3.2 起，LlmProvider trait 及其关联类型 ProviderCapabilities / ProviderFeatures 从 provider 模块移至 llm 模块根级别，归属 #[cfg(feature = "llm")] 而非 any(provider-*)。纯 Mock 场景不再需要引入任何 provider feature。

旧路径（v0.3.0）	新路径（v0.3.2）
agcore::llm::provider::LlmProvider	agcore::llm::LlmProvider
agcore::llm::provider::ProviderCapabilities	agcore::llm::ProviderCapabilities
agcore::llm::provider::ProviderFeatures	agcore::llm::ProviderFeatures

向后兼容：provider 模块中保留了 pub use 重导出，老路径仍可编译。但推荐迁移至新路径，未来版本可能移除重导出。

ProviderConfig / ProviderType / create_provider() 等 provider 创建逻辑仍在 agcore::llm::provider 下，无需迁移。

迁移步骤

# 1. 全局替换 use 路径
sed -i 's/agcore::llm::provider::LlmProvider/agcore::llm::LlmProvider/g' src/**/*.rs
sed -i 's/agcore::llm::provider::{LlmProvider/agcore::llm::{LlmProvider/g' src/**/*.rs

# 2. 验证编译
cargo build --features "full"

核心模块

模块	一句话说明
agcore::llm	LLM 调用周期（LlmProvider trait + LlmCycle 重试/用量 + 流式工具循环 + auto-compaction + Hook + Embedding trait + 公开 MockProvider）
agcore::prompt	提示词工程（PromptTemplate 变量插值 + PromptTemplateRegistry + PromptComposer 多角色消息构造 + validate_messages）
agcore::tools	工具系统（BaseTool trait + ToolRegistry 注册/调用 + PermissionChecker 黑白名单 + MCP stdio 客户端）
agcore::memory	记忆系统（MemoryStore trait + InMemoryStore / SqliteStore + ConversationMemory 滑动窗口 + KnowledgeStore + KnowledgeGraph 图谱 + VectorStore 向量 + RagPipeline + MemoryRetriever 混合检索）
agcore::agent	Agent 运行时（Agent trait + AgentBuilder + RuntimeBundle + AgentSession + 多上下文分区 + 摘要自动生成 + 快照恢复 + Plan/Step 任务编排）
agcore::engine	Agent 执行引擎（SessionManager 会话树 + Checkpointer time-travel 快照 + 子任务分发 + Agent 热切换）
agcore::document	文档分割（Document 类型 + RecursiveCharacterSplitter 递归字符级分割）

架构关系图

┌─────────────────────────────────────────────────────────────┐
│  应用层 (TUI / Bot 网关 / 业务服务)                           │
└───────────────────────────┬─────────────────────────────────┘
                            │ 使用
┌───────────────────────────▼─────────────────────────────────┐
│  Agent Engine  (agcore::engine)                               │
│  SessionManager / Checkpointer / SubTask 分发 / Agent 切换    │
└───────────────────────────┬─────────────────────────────────┘
                            │ 编排
┌───────────────────────────▼─────────────────────────────────┐
│  Agent Runtime  (agcore::agent)                               │
│  Agent / AgentBuilder / RuntimeBundle / AgentSession /      │
│  ContextSlot / SummaryConfig / Plan / Step                   │
└─────┬───────────────┬───────────────┬───────────────┬───────┘
      │               │               │               │
┌─────▼─────┐  ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│  LLM      │  │  Prompt     │ │  Tool       │ │  Memory     │
│  agcore:: │  │  agcore::   │ │  agcore::   │ │  agcore::   │
│  llm      │  │  prompt     │ │  tools      │ │  memory     │
└─────┬─────┘  └─────────────┘ └─────┬───────┘ └──────┬──────┘
      │                               │                │
      │    ┌──────────┐               │    ┌───────────┴──────┐
      │    │ Document │               │    │  Graph / Vector  │
      │    │ agcore:: │               │    │  RagPipeline    │
      │    │ document │               │    │  Retriever      │
      │    └──────────┘               │    └──────────────────┘
      └──────────────┬────────────────┘
                     ▼
            ┌─────────────────┐
            │  Mock Provider  │
            │  公开 API       │     离线测试 / 示例
            └─────────────────┘

模块依赖关系

graph BT
    LLM["<b>llm</b><br/>Provider / Cycle /<br/>Hooks / Stream /<br/>Compact / Embedding /<br/>Mock"]:::core
    Prompt["<b>prompt</b><br/>Template / Composer"]:::core
    Tool["<b>tools</b><br/>BaseTool / Registry /<br/>MCP"]:::core
    Memory["<b>memory</b><br/>Store / Conversation /<br/>Knowledge / Graph /<br/>VectorStore / RagPipeline /<br/>Retriever"]:::core
    Agent["<b>agent</b><br/>Agent / Builder /<br/>Session / ContextSlot /<br/>Summary / Plan"]:::core
    Engine["<b>engine</b><br/>SessionManager /<br/>Checkpointer /<br/>SubTask / Switch"]:::phase
    Document["<b>document</b><br/>Splitter"]:::phase

    Prompt --> LLM
    Tool --> LLM
    Memory --> LLM
    Memory --> Document
    Document --> LLM
    Agent --> LLM
    Agent --> Tool
    Agent --> Memory
    Engine --> Agent

    classDef core fill:#60a5fa,stroke:#2563eb,color:#fff
    classDef phase fill:#a78bfa,stroke:#7c3aed,color:#fff

依赖规则：

• llm 被 agent / engine 使用，同时 llm::cycle 依赖 tools::ToolRegistry（用于工具调用循环）
• prompt / tools 互不依赖，可独立使用；memory 依赖 document（向量存储的分割器）和 llm（embedding trait）
• agent 编译期依赖 llm / tools / memory，与 prompt / document 无直接编译依赖（system prompt 以 &str 形式传入，文档分割由应用层处理）
• engine 编译期依赖 agent，提供会话树管理和快照恢复能力
• 上层应用通常依赖 engine（完整能力）或 agent（轻量场景），不应跨层直接 use

环境变量

AG Core 库本身不读环境变量。下表是 examples/simple_visit.rs 这一真实调用示例所使用的环境变量，以及通常推荐的取值。

变量	必填	推荐值	说明
OPENAI_API_KEY	用 OpenAI 时	—	OpenAI / 兼容 Provider（DeepSeek / Qwen）的 API key
OPENAI_BASE_URL	是	https://api.openai.com/v1	OpenAI 兼容端点 base URL（DeepSeek/Qwen 用对应地址）
OPENAI_MODEL	是	gpt-4o-mini	OpenAI 模型名
ANTHROPIC_API_KEY	用 Anthropic 时	—	Anthropic Claude API key
ANTHROPIC_BASE_URL	是	https://api.anthropic.com	Anthropic 兼容端点 base URL
ANTHROPIC_MODEL	是	claude-3-5-sonnet-latest	Claude 模型名
PROVIDER	否	openai	Provider 类型：openai / anthropic / deepseek / qwen / ollama
RUST_LOG	否	agcore=info	tracing 日志级别（其他 crate 可加 =debug）

示例（运行 examples/simple_visit.rs 真实调用 OpenAI）：

export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://api.openai.com/v1
export OPENAI_MODEL=gpt-4o-mini
export PROVIDER=openai
export RUST_LOG=agcore=debug
cargo run --example simple_visit

参考项目

AG Core 在 Phase 4 设计阶段调研了 4 个 2026 年公开的 AI Agent 项目（详见 docs/note-agent-harness-references.md）：

项目	类型	语言	借鉴点
OpenClaw	消息网关	TypeScript	多渠道适配模式
Hermes Agent	自主学习智能体	Python	实体与会话解耦
OpenHuman	桌面助手	Rust + Tauri	记忆树与 Token 压缩
OpenHarness	Agent Harness 框架	Python	显式依赖注入容器 + 三级权限

AG Core 借鉴了以下架构模式（不直接复用代码）：

• OpenHarness 风格 —— 显式 RuntimeBundle 依赖注入容器
• Hermes 风格 —— Agent trait（角色）与 AgentSession（会话）解耦

后续 v0.2+ 计划借鉴 OpenHuman 的 Memory Tree / TokenJuice 模式。

许可证

本项目基于 Apache License 2.0 授权。完整文本见 LICENSE。

Copyright 2026 AG Core Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0