ai_agent工具mcp
前言
本文主要介绍个人 Agent 框架 cc_agent
的设计与实现,包括用户管理、会话管理、模型配置、Skill、MCP
工具调用以及完整的对话流程。
姑且将 AI 系列后续内容分为以下 4 个部分:
学术篇:
LLM
基础知识、模型训练、各类算法的原理与实现等。
开发篇:
Agent 框架、各类 AI 应用的开发等。
运维篇:
Agent 应用的部署、推理参数测试等。
杂项:
AI
渗透、视频生成、音频生成、超分辨率等其他内容。
前天已经完成了 Agent 框架的全部基础组件,不过目前还在开发类似 Voyager
的自学习 Skill
功能。考虑到博客已经有一段时间没有更新了,就先整理一下目前的开发成果。
这次主要介绍自己开发的 Agent 框架。
首先需要明确一点:Agent 并不是简单地接入一个
LLM,再封装一层输入输出就能实现的。LLM 只是 Agent
的一部分,可以把它理解为 Agent
的「大脑」,负责理解、思考和决策,而其他组件则负责提供必要的功能和支持。
以人为例,人由大脑、眼睛、耳朵、四肢等多个部分组成,各个部分相互配合才能构成一个完整的人。Agent
也是如此,需要多个组件协同工作,才能完成完整的任务流程。
因此,这篇文章主要介绍如何构建 Agent
的各个组件,以及如何将它们组织起来,最终组成一个完整的
Agent。具体实现会在正文中逐一介绍。
开发 Agent,本质上也是在开发 Agent 框架。
那么,什么是 Agent 框架?简单来说,就是一套用于组织 Agent
组件、管理组件之间交互,以及实现任务执行流程的方法和规则。
既然市面上已经有这么多成熟的框架,为什么还要自己开发?
主要有三个原因:
学习目的:阅读源码固然能够了解框架的实现原理,但很多东西只有自己动手实现一遍,才能真正理解其中的设计思路和组件之间的关系。
满足自己的需求:现有框架不一定完全符合自己的使用习惯和开发需求。可能缺少某些功能,也可能在扩展已有功能时受到框架本身的限制。自己开发则可以根据实际需求灵活调整。
方便后续复用:后续还会尝试开发各种 Agent
功能和相关项目。如果每次都从头实现一遍基础组件,显然没有必要。拥有一套自己的框架,就可以直接复用已有功能,在此基础上进行扩展。
cc_agent 代码仓库:https://github.com/zusda/cc_agent/tree/main
1. 框架概览
自己开发的框架总觉得应该起个名字,否则连导入包的时候都不知道该叫什么。
这里将其命名为 cc_agent。
cc_agent 是一个单 Agent
框架,以用户为隔离单位。每个用户拥有独立的会话(session)、模型配置(model_cfg)和技能(skill)。
工具统一添加到模型配置中,并通过 MCP 服务提供和调用。
源码目录(包名
cc_agent
):
config.py
:全局目录与窗口参数,包括
USER_DIR
、
MODEL_CFG_DIR
、
SKILL_DIR
、
MAX_MESSAGES
、
COMPACT_COUNT
。
users/user.py
:
User
类,负责用户相关信息的管理。
users/model_cfg.py
:
ModelCfg
类和
check_name
函数,负责模型配置及相关检查。
skill.py
:
Skill
类,负责技能的管理。
agent/agent.py
:
Agent
类,负责整合各个组件,构建完整的 Agent 实例。
message/message.py
:
Message
数据类和各种消息创建函数。
message/SessionHistory.py
:
SessionHistory
类,负责会话历史的读取、保存与压缩。
mcp_server/
:MCP 服务端与客户端,包含
get_tools
、
execute_tool
、
ToolExecuteError
等功能,以及相关工具函数。
model/
:模型层封装,统一不同模型的调用接口,提供具有统一调用方法的模型实例。
2. 组件介绍
cc_agent 主要由以下组件组成:
User(用户)
Message(消息)
SessionHistory(会话历史)
ModelCfg(模型配置)
Skill(技能)
Agent(智能体)
Model(模型类)
Tool(工具,包括 MCP 服务端与客户端)
2.1 组件组合设计
在 cc_agent 中,User
是数据隔离的最小单位,用户名全局唯一。每个用户在本地
USER_DIR
下拥有独立的目录,用于存放自己的会话、模型配置和技能。
用户的本地目录结构如下:
1
2
3
4
5
6
7
8
9
10
USER_DIR/
└── <user_name>/
├── <user_name>.json 记录 user_name、session_id、model_cfg
├── session/
│ └── <session_id>.jsonl 一个会话一个文件,每行一条消息
├── model_cfg/
│ └── <cfg_name>.json 用户自己的模型配置
└── skills/
└── <skill_name>/
└── SKILL.md 用户自己的技能
User 内部维护两个主要列表:
session_id
:记录用户拥有的会话 ID。
model_cfg
:记录用户拥有的模型配置名称。
2.1.1 Message 与 SessionHistory
session_id
用于标识用户与 Agent
之间的一段会话。每段会话对应一个 JSONL
文件,其中每一行都是一条独立的消息。
消息由
Message
类管理,负责定义和创建不同类型的消息。例如:
1
2
{
"role"
:
"user"
,
"content"
:
"北京今天天气怎么样?"
}
{
"role"
:
"agent"
,
"content"
:
"北京今天晴,气温 8 到 18 度,早晚温差较大,建议带件外套。"
}
这里的
Message
负责消息结构的定义,而
SessionHistory
负责会话历史的管理。
SessionHistory
根据
session_id
读取对应的
JSONL 文件,将当前需要使用的历史消息加载到
history_message
中,并提供消息保存、历史压缩等功能。
它并不需要始终将整个 JSONL 文件加载到内存中,只需要保留 Agent
当前运行所需的历史消息即可。
2.1.2 ModelCfg(模型配置)
ModelCfg
是模型配置类,用于管理 Agent 使用的模型、工具和
Skill。
User 的
model_cfg
列表只记录模型配置名称,而不是直接保存模型配置实例。需要使用某个配置时,再通过
User 加载对应的
ModelCfg
实例。
模型配置支持全局和用户两种归属方式:
全局配置:新创建的
ModelCfg
默认没有用户归属,即
self.belong = None
。此时调用
save()
,配置会保存到全局的模型配置目录,供后续加载和复用。
用户配置:当 User
添加一个模型配置时,会将配置复制并保存到该用户自己的
model_cfg
目录中。后续调用
user.get_model_cfg(cfg_name)
,即可根据名称加载该用户对应的配置实例。
2.1.3 Skill(技能)
Skill 的存储和归属机制与 ModelCfg 类似。
默认情况下,Skill 保存到全局目录。只有当一个具有用户归属的
ModelCfg
添加 Skill 时,才会将对应的 Skill
复制到该用户自己的
skills
目录下。
如果没有用户归属的全局
ModelCfg
添加 Skill,那么该 Skill
仍然保存到全局目录。
模型配置中会记录所使用的 Skill 名称。虽然用户目录下可能存放多个
Skill,但只有被当前
ModelCfg
记录的
Skill,才会被加载到对应的 Agent 中。
2.1.4 Agent 组合
ModelCfg 中主要记录以下内容:
使用什么模型:由 Model 层提供。
拥有哪些工具:通过 MCP 服务添加。
拥有哪些 Skill:根据 Skill 名称加载对应技能。
一次完整的 Agent 初始化,需要准备两个核心对象:
通过 User 提供的
session_id
,创建对应的
SessionHistory
实例,获取会话历史。
通过 User 提供的模型配置名称,加载对应的
ModelCfg
实例。
随后,将这两个实例和系统提示词(
system_prompt
)传入
Agent,即可完成 Agent 的初始化。
1
2
3
class
Agent
:
def
__init__
(
self, history, model_cfg, system_prompt=
""
):
...
Agent
内部包含许多辅助功能,但其核心是实现一个持续运行的交互循环(Loop),负责协调模型调用、工具执行、消息处理等操作。
loop工作循环图
2.2 一轮对话的完整示例
下面通过一个实际示例,将前面介绍的组件串联起来。
运行前需要满足以下条件:
Ollama 中已经下载
qwen3:8b
。
MCP 服务已经在
http://localhost:8000/mcp
启动。
MCP 服务已经注册了
add
工具。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
import
asyncio
from
cc_agent.agent.agent
import
Agent
from
cc_agent.message.SessionHistory
import
SessionHistory
from
cc_agent.skill
import
Skill
from
cc_agent.users.model_cfg
import
ModelCfg
from
cc_agent.users.user
import
User
USER_NAME =
"demo_user"
CFG_NAME =
"qwen3_8b"
SERVER_NAME =
"local"
MCP_URL =
"http://localhost:8000/mcp"
async
def
main
():
# 1. 创建用户
user = User.create_user(USER_NAME)
# 2. 创建 session 和历史对象
session_id = user.new_session()
history = SessionHistory(USER_NAME, session_id)
# 3. 创建模型配置并添加到用户
new_cfg = ModelCfg(
CFG_NAME,
model_name=
"qwen3:8b"
,
url=
"http://localhost:11434/v1"
,
type
=
"ollama"
,
)
user.add_model_cfg(new_cfg)
# 根据 cfg_name 获取用户自己的配置实例
model_cfg = user.get_model_cfg(CFG_NAME)
# 4. 登记 MCP 服务并添加工具
model_cfg.add_server(SERVER_NAME, MCP_URL)
tool_name =
await
model_cfg.add_tool(SERVER_NAME,
"add"
)
# 返回 "local__add"
# 目前仅支持最基础的单工具添加方式
# 5. 添加 Skill
# 结构:{name, description, content}
skill = Skill(
"answer-format"
,
"用户要求计算时使用,规定回复的格式"
,
"计算完成后,回复只能写成:计算结果:<数字>"
,
)
# 自动复制到用户的 skills 目录
# 因为当前 model_cfg 已经具有用户归属
model_cfg.add_skill(skill)
# 6. 创建 Agent
# 工具和 Skill 需要在创建 Agent 之前添加完成
agent = Agent(
history,
model_cfg,
system_prompt=
"You are a helpful assistant."
)
# 7. 发起一轮对话
reply =
await
agent.generate(
"请用工具计算 123.5 加 876.5"
)
print
(reply)
asyncio.run(main())
以上代码展示了从创建用户、初始化会话、配置模型,到添加工具和
Skill,最后创建 Agent 并完成一次交互的完整过程。
2.3 User(用户)
前面介绍了 User
在整个框架中的作用:它是数据隔离的最小单位,负责管理用户自己的会话、模型配置和技能。
采用这种以用户为单位的目录结构,主要是为了方便后续扩展。
例如:
单机个体agent:只需要固定一个 User 和一个 Session,即可作为个体
Agent 使用。
团队协作:可以在此基础上扩展用户体系,将不同用户或团队的数据进行隔离。
Web 聊天应用:类似 GPT 的聊天机器人,可以为用户创建多个
Session,并允许用户添加和管理不同的模型配置。
目前框架没有设计用户等级、权限等分级系统,主要考虑的是单用户 Agent
的使用场景。后续如果有需要,再扩展相关功能。
用户管理
以下均为类方法,可以直接通过
User.xxx()
调用。
User.create_user(user_name)
:创建用户,同时生成对应的目录结构。
User.open_user(user_name)
:打开已有用户,返回对应的
User 实例。
User.delete_user(user_name)
:删除用户及其整个目录。
User.list_user()
:打印并返回所有用户名,以
USER_DIR
下的子文件夹作为用户记录。
会话管理
new_session()
:创建一个新的空 JSONL 文件,并返回对应的
session_id
。
delete_session(session_id)
:删除指定 Session
对应的文件及用户记录中的 ID。
list_session()
:打印并返回当前用户拥有的 Session ID
列表。
模型配置管理
add_model_cfg(model_cfg, cfg_name=None)
:将传入的模型配置复制到用户自己的目录中,并返回最终使用的配置名称。
get_model_cfg(cfg_name)
:根据配置名称,加载用户自己的
ModelCfg
实例。
list_model_cfg()
:打印并返回当前用户拥有的模型配置名称列表。
delete_model_cfg(cfg_name)
:删除指定模型配置文件及其记录。
技能查询
-
list_skill_name()
:打印并返回当前用户拥有的 Skill
名称列表。
这里需要特别说明一下,
list_skill_name()
并不是直接扫描用户的
skills
目录,而是读取用户所有模型配置中记录的 Skill 名称,然后合并去重。
这样设计是因为 Skill 文件可能被多个模型配置共同使用。
例如,模型配置 A 和 B 都使用了 Skill X。如果删除模型配置 A 时直接删除
Skill X,那么模型配置 B 就无法继续使用该技能。
因此,目前删除模型配置时,只会移除对应配置中记录的 Skill
名称,不会直接删除 Skill 文件。通过汇总所有模型配置中的 Skill
名称,就可以得到当前仍被使用的技能列表。
后续可以在此基础上增加无用 Skill 的清理功能,目前暂不实现。
2.4 Message(消息)
Message 是会话历史中的最小单位,一条 Message 对应 JSONL
文件中的一行记录。
2.4.1 消息字段
Message 包含以下字段:
role
:消息角色,包括
user
、
agent
、
tool
、
context
。
type
:消息类型,包括
plain
和
tool_call
。
content
:消息内容。
plain
类型为字符串,
tool_call
类型为字典,记录工具名称和调用参数。
seq
:消息在会话中的序号,从 1 开始递增,由
SessionHistory 在添加消息时自动分配。
call_id
:工具调用
ID,用于关联工具调用消息与对应的执行结果。
start
、
end
:context
消息的摘要范围,记录本次摘要覆盖的消息序号。
2.4.2 消息类型
根据
role
和
type
的组合,目前有以下五种消息:
user
+
plain
:用户输入。
agent
+
plain
:Agent 的普通回复。
agent
+
tool_call
:Agent
发起的工具调用。
tool
+
plain
:工具执行结果,执行失败时以
tool error:
开头。
context
+
plain
:历史消息压缩后的摘要,作为当前消息窗口的第一条消息。
2.4.3 消息创建与转换
提供以下函数创建不同类型的消息:
createUserMessage(text)
:创建用户消息。
createAiMessage(text)
:创建 Agent 普通回复。
create_AiToolCall_Message(name, arguments, call_id=None)
:创建工具调用消息,不传入
call_id
时自动生成。
create_ToolResult_Message(text, call_id)
:创建工具执行结果。
createContextMessage(text, start, end)
:创建历史摘要消息。
此外,还提供两个转换方法:
toJson()
:将 Message 实例转换为 JSON 字符串。
Message.fromJson(text)
:将 JSON 字符串解析为 Message
实例。
2.5 SessionHistory(会话历史)
每个 Session 对应一个 JSONL 文件,存储路径为:
1
USER_DIR/<user_name>/session/<session_id>.jsonl
SessionHistory
是会话历史的内存管理器,负责消息的读取、写入和压缩。Agent
不直接操作会话文件,而是通过 SessionHistory 管理消息。
初始化方式:
1
messages = SessionHistory(user_id, session_id)
其中
user_id
实际上是用户名,对应的 Session
文件必须已经存在。
SessionHistory 内部维护一个
messages
列表,每个元素都是
Message 实例。初始化时逐行读取 JSONL 文件,并通过
Message.fromJson(line)
转换为对象。
Agent 与 SessionHistory 共用同一个对象引用,因此 Agent
对消息的修改会直接反映在 SessionHistory 中。
目前框架没有实现文件锁或并发写入保护,因此同一个 Session
同一时间只应由一个 Agent 写入。
2.5.1 基本方法
add(message)
:为消息分配序号,并添加到内存中的
messages
列表,不立即写入文件。
save()
:将新增消息追加写入 JSONL 文件。
load()
:重新读取 JSONL 文件,并返回消息列表。
await checkCompact()
:检查是否满足压缩条件,满足时执行压缩。
await compact()
:执行历史消息压缩。
2.5.2 JSONL 消息存储
会话文件采用 JSONL 格式,每行保存一条完整的 JSON
消息。普通保存采用追加写入,不会覆盖之前的记录。
例如,一轮包含工具调用的对话:
1
2
3
4
{
"role"
:
"user"
,
"type"
:
"plain"
,
"content"
:
"请用工具计算 123.5 加 876.5"
,
"seq"
:
1
,
"call_id"
:
null
,
"start"
:
null
,
"end"
:
null
}
{
"role"
:
"agent"
,
"type"
:
"tool_call"
,
"content"
:
{
"name"
:
"local__add"
,
"arguments"
:
{
"a"
:
123.5
,
"b"
:
876.5
}
,
"seq"
:
2
,
"call_id"
:
"a1b2c3d4"
,
"start"
:
null
,
"end"
:
null
}
{
"role"
:
"tool"
,
"type"
:
"plain"
,
"content"
:
"1000.0"
,
"seq"
:
3
,
"call_id"
:
"a1b2c3d4"
,
"start"
:
null
,
"end"
:
null
}
{
"role"
:
"agent"
,
"type"
:
"plain"
,
"content"
:
"结果是 1000。"
,
"seq"
:
4
,
"call_id"
:
null
,
"start"
:
null
,
"end"
:
null
}
2.5.3 消息窗口
JSONL 文件保留完整的历史记录,而内存中的
messages
只加载当前消息窗口。
加载规则:
如果文件中没有
context
消息,则加载全部历史记录。
如果存在
context
消息,则从最后一条
context
消息开始,加载该消息及其后面的所有记录。
context
保存此前历史消息的摘要。生成模型输入时,Agent
会将其内容拼接到 System Prompt 后面,而不是作为独立消息发送。
因此,两者的区别是:
messages
:当前窗口中的消息。
JSONL 文件:完整的历史记录,包括压缩前的旧消息。
2.5.4 历史消息压缩
当一轮对话结束并保存消息后,SessionHistory
会检查当前窗口的消息数量。如果达到
MAX_MESSAGES
,则触发压缩。
压缩范围
从当前窗口中取最旧的
COMPACT_COUNT
条消息进行压缩。如果第一条消息是上一次压缩生成的
context
,也会一并纳入本次压缩,使摘要逐级叠加。
切分位置会向后移动到下一条文字消息,避免在切分后留下不完整的工具调用记录。
生成摘要
CompressModel
只处理
plain
类型的消息,将其整理为“角色: 内容”的文本,再调用本地 Ollama 的
qwen3:8b
生成摘要。
提示词要求模型保留关键事实,并将内容压缩至原文长度的约
70%。这个比例是提示词要求的目标,并不保证实际输出长度。
压缩结果
压缩完成后,内存中的消息窗口变为:
一条新的
context
摘要消息。
尚未参与压缩的剩余消息。
随后重新分配消息序号,并将整个新窗口追加写入 JSONL 文件。
默认配置为:
MAX_MESSAGES = 300
COMPACT_COUNT = 200
因此,触发压缩时会处理约 200 条消息,保留约 100
条未压缩消息,最终窗口约为 101 条。
压缩不会删除文件中的旧记录,而是将新的消息窗口追加到文件末尾。由于加载时只读取最后一条
context
及其后续记录,因此不会重复加载旧消息。
注意事项
tool_call
类型的消息不会参与摘要,因此工具名称和调用参数不会保留在摘要中。工具执行结果属于
plain
消息,会参与摘要,但摘要可能无法准确保留它与原工具调用之间的对应关系。
压缩使用的
CompressModel
独立于 ModelCfg,默认调用本地
Ollama 的
qwen3:8b
。执行压缩前,需要确保 Ollama
服务和对应模型可用。
2.6 ModelCfg(模型配置)
ModelCfg 用于管理 Agent 的模型配置,同时记录 MCP 服务、工具和
Skill。
工具与 Skill 都绑定在 ModelCfg 上。Agent 使用不同的 ModelCfg
时,会加载对应配置中记录的工具和 Skill。
2.6.1 初始化与配置字段
初始化方式:
1
ModelCfg(cfg_name, model_name, url, key=
None
,
type
=
"ollama"
)
主要字段:
cfg_name
:配置名称,必填,同时作为配置文件名。
model_name
:模型名称。
url
:模型 API 服务地址。
key
:服务商 API Key,使用本地 Ollama 时可以留空。
type
:模型类型,目前定义了
ollama
、
vllm
、
deepseek
,但 Agent
当前只支持
ollama
。
belong
:配置归属用户名,
None
表示全局配置。
2.6.2 MCP 服务与工具管理
ModelCfg 提供以下方法管理 MCP 服务和工具:
MCP 服务管理
add_server(server_name, url)
:添加 MCP
服务,建立服务别名与 URL 的映射。
list_server()
:列出已添加的 MCP 服务。
delete_server(server_name)
:删除指定 MCP 服务。
工具管理
await add_tool(server_name, func_name)
:从指定 MCP
服务获取工具并添加到配置中,返回带服务别名前缀的工具名称,例如
local__add
。
list_tool()
:列出已添加的工具。
delete_tool(tool_name)
:删除指定工具。
to_openai_tools()
:将工具转换为 OpenAI API
兼容的工具格式。
Agent 调用模型时,会将转换后的工具列表传入模型:
1
llm.generate(openai_messages,
self
.tools)
具体的消息和工具格式处理由模型类负责。对于非 OpenAI
兼容的模型,需要在对应模型类中将这些数据转换为模型支持的输入格式。
2.6.3 Skill 管理
ModelCfg 通过以下方法管理 Skill:
add_skill(skill)
:添加 Skill。
list_skill()
:列出已添加的 Skill。
delete_skill(skill_name)
:移除指定 Skill。
ModelCfg 只记录 Skill 名称,不直接保存 Skill 内容。删除 Skill
时,也只会从配置中移除名称,不会删除对应的 Skill 文件。
2.6.4 配置文件管理
ModelCfg 提供以下方法管理配置文件:
save()
:保存配置。
delete()
:删除配置文件。
ModelCfg.load_global(cfg_name)
:根据配置名称,从全局配置目录加载配置。
ModelCfg.load(file_path)
:根据指定路径加载配置。
配置文件采用 JSON 格式,以
cfg_name
命名。
保存规则
新建 ModelCfg 对象时,配置只保存在内存中,不会自动写入文件。
全局配置需要显式调用
save()
,保存到
MODEL_CFG_DIR
。如果存在同名配置,则报错。
用户配置通过
User.add_model_cfg()
复制到对应用户目录。
配置文件创建后,后续对 MCP 服务、工具和 Skill
的修改会自动写回配置文件。
2.7 Skill(技能)
Skill 是一份提供给模型的指令文档,通常保存为
SKILL.md
。模型通过
description
判断是否需要使用该 Skill,只有调用
load_skill
工具后,才会获取完整的
content
。
1
Skill(name, description, content)
# description 必须为单行
文件格式:
1
2
3
4
5
6
---
name: code-review
description: 审查 Python 代码时使用
---
(正文,可以很长)
存放位置:
全局:
SKILL_DIR/<name>/SKILL.md
用户:
USER_DIR/<user_name>/skills/<name>/SKILL.md
每个 Skill 使用独立文件夹存放,而不是直接保存为单个文件。这样可以在
Skill
需要额外附件(如脚本、配置文件等)时,将它们放在对应目录下,方便统一管理。
方法:
save(overwrite=False)
:保存 Skill。
belong
为
None
时保存到全局目录,否则保存到指定用户目录。默认不覆盖已有的同名文件。
Skill.load(name, belong=None)
:加载 Skill,返回对应的
Skill 对象。
belong=None
时从全局目录加载;指定
belong=user_name
时,从对应用户目录加载。
Skill.exists(name, belong=None)
:判断指定目录下是否存在该
Skill。
Skill.path_of(name, belong=None)
:根据 Skill
名称和归属生成文件路径,供加载等操作使用。
copy_to_user(user_name)
:将 Skill
复制到指定用户目录。如果目标目录已存在同名
Skill,则直接复用,不覆盖。
delete()
:删除 Skill 文件。如果仍有模型配置引用该
Skill,则拒绝删除,并提示正在使用它的模型配置。
prompt_line()
:将 Skill 转换为一行提示词,用于追加到
system prompt 中。
2.8 Agent(智能体)
Agent
负责执行一轮完整的对话。它将历史消息、用户输入和工具列表发送给模型;如果模型需要调用工具,就执行对应工具,并将执行结果返回给模型,直到模型生成最终回复。
1
Agent(history, model_cfg, system_prompt="")
参数:
history
:当前会话的
SessionHistory
对象。
model_cfg
:当前用户的
ModelCfg
对象。
初始化过程:
创建 Agent 时,会读取一次模型配置,并完成以下操作:
根据配置中的
type
创建对应的模型对象。
获取可用的工具列表。
加载配置中记录的 Skill。如果对应的 Skill
文件不存在,则直接报错。
如果配置中包含 Skill,则在 system prompt 后追加 Skill
列表,并注册一个内置工具
load_skill
,供模型按需加载 Skill
的完整内容。
方法:
await generate(user_input)
:执行一轮完整对话,返回最终回复文本。内部通过循环处理模型回复和工具调用,最多调用模型
MAX_STEPS
次。超过限制后抛出异常,本轮消息不会保存。
await run_tool(call_message)
:执行一条工具调用,并返回工具结果消息。如果执行出错,不会直接抛出异常,而是返回一段以
tool error:
开头的错误信息,交给模型自行分析和修正。
parse_arguments(raw_arguments)
:将模型返回的参数字符串解析为字典。
2.9 Model 与模型类
Model 层负责封装不同服务商的模型接口,对上层 Agent
提供统一的调用方式。无论底层使用哪种模型,最终都会通过统一的
Model
接口供 Agent 调用。
Model 基类
Model
是模型基类,只定义了一个接口方法:
1
await generate(messages, tools=None)
messages
:消息列表。
tools
:工具列表,可选。
该方法负责将消息和工具发送给底层模型,并返回模型的回复内容。
OllamaOpenAI
目前实现的一个模型类是
OllamaOpenAI(model_name, base_url)
。
该类通过 Ollama 提供的 OpenAI 兼容接口调用模型,API Key 固定设置为
"ollama"
。
目前本地使用的是
qwen3:8b
,因此
generate()
内部实现 接收的
messages
和
tools
均采用
OpenAI 兼容格式。
CompressModel
另一个模型类是
CompressModel
,同样继承自
Model
,但用途不同。
它专门用于历史消息压缩,不参与 Agent 的常规对话和工具调用流程。
2.10 MCP 服务与客户端
cc_agent 内部的工具统一通过 MCP 服务提供,因此项目内部也实现了一个
MCP 服务器。需要添加工具时,只需在
cc_agent/mcp_server/functions/
目录下编写工具函数,服务器启动时会自动加载该目录下定义的工具。
例如,在
cc_agent/mcp_server/functions/calc.py
中编写:
1
2
3
4
5
def
add
(
a:
float
, b:
float
) ->
float
:
"""计算两个数之和。"""
return
a + b
TOOLS = [add]
其中,
TOOLS
用于指定该文件需要注册为 MCP
工具的函数,服务器会自动加载其中的所有函数。
启动 MCP 服务器:
1
python -m cc_agent.mcp_server.server
当然,也可以直接使用自己的 MCP 服务器。cc_agent 不依赖特定的 MCP
服务端实现,只要能够通过 MCP 协议获取工具列表并执行工具即可。
MCP 客户端
client.py
提供了操作 MCP
服务的辅助函数,主要负责获取工具列表和执行具体工具:
client.get_tools(url)
:异步获取指定 MCP
服务的工具列表,并转换为 OpenAI
格式。获取结果带有缓存,避免重复请求。
client.execute_tool(url, name, arguments)
:异步执行指定工具,传入服务地址、工具名称和参数。执行失败时抛出
ToolExecuteError
。
客户端内部还实现了
tools_cache
缓存机制。获取工具列表时,会优先检查缓存,只有缓存中不存在对应数据时,才会连接目标
MCP 服务获取。
2.11 config.py
config.py
是项目的全局配置文件,主要用于统一管理数据存储路径和运行参数。
所有路径均以运行脚本时的当前工作目录(
Path.cwd()
)为基准。因此,从不同目录启动脚本,生成的数据也会存放在不同位置。
主要配置:
USER_DIR
:
users_data/
,用户数据根目录。
MODEL_CFG_DIR
:
model_cfg_data/
,全局模型配置目录。
SKILL_DIR
:
skills_data/
,全局 Skill
存储目录。
MAX_MESSAGES
:
300
,会话历史达到该消息数量时触发压缩。
COMPACT_COUNT
:
200
,每次压缩时选取最旧的消息数量。
3. 组件之间的关系
3.1
按用户隔离,全局与用户两级存储
ModelCfg
和
Skill
都支持全局和用户两种归属,通过
belong
区分:
全局配置:
belong=None
,保存在全局目录(
MODEL_CFG_DIR
、
SKILL_DIR
)。创建时如果没有指定用户,则默认保存在全局目录。
用户配置:
belong
为用户名,保存在对应用户的目录下。不同用户的数据相互隔离。
3.2 用户、会话与 Agent
用户名唯一,一个用户可以创建多个 session,每个 session
独立记录对话历史。
每个 session 对应一个
SessionHistory
对象,通过读取对应的 JSONL 文件恢复历史消息。
创建 Agent 需要两个核心对象:当前 session 的
SessionHistory
和一个
ModelCfg
。
Agent 根据
SessionHistory
获取对话历史,根据
ModelCfg
获取模型、工具和 Skill 配置。
3.3 工具、Skill 与 ModelCfg
工具和 Skill 都需要添加到指定的
ModelCfg
中才能使用。它们绑定在具体的模型配置上,不同的
ModelCfg
可以拥有不同的工具和 Skill。
Skill:每个
ModelCfg
只记录自己添加过的 Skill
名称,不需要包含所有 Skill。Agent 初始化时根据这些名称加载对应的
Skill。
工具:只能通过 MCP 服务获取,
ModelCfg
记录 MCP
服务的别名与 URL,以及已添加的工具。
工具命名:工具名会添加服务别名前缀,格式为
服务别名__原始名称
,例如
local__add
,用于避免不同 MCP 服务之间出现工具重名。
重复添加:同一个
ModelCfg
中添加同名工具会抛出异常。
3.4 关系图
1
2
3
4
5
6
7
8
9
10
User ──┬── session(xxx.jsonl) ──── SessionHistory ─────┐
│ ├──► Agent(history, model_cfg, system_prompt)
├── model_cfg ──┬── servers (别名→url) ─────────┘ │
│ ├── tools (来自 MCP) ├─ 调用模型 (OllamaOpenAI)
│ └── skill 名字 ──► skills/<name>/SKILL.md │
│ └─ 执行工具 (mcp client)
└── skills (用户目录下的副本)
全局目录:MODEL_CFG_DIR、SKILL_DIR
用户 add 时,复制一份到用户目录
4. 使用流程
4.1 创建用户
1
user = User.create_user(
"demo_user"
)
如果用户已经存在,可以使用
User.open_user("demo_user")
打开已有用户。
创建用户后,会在
USER_DIR
下生成对应的用户目录,并自动创建三个子目录:
session/
:存放用户的会话历史文件。
model_cfg/
:存放用户的模型配置。
skills/
:存放用户的 Skill 副本。
4.2 创建 session
1
2
session_id = user.new_session()
history = SessionHistory(
"demo_user"
, session_id)
new_session()
只负责创建会话并返回
session_id
,不会直接返回历史对象。因此,还需要通过用户名和会话
ID 创建
SessionHistory
,用于读取和管理该会话的消息历史。
4.3 创建模型配置并添加工具
创建
ModelCfg
对象,通过
user.add_model_cfg(...)
将其添加到用户配置中。
使用
user.get_model_cfg(cfg_name)
获取用户目录下的模型配置对象。后续操作应针对这个对象,而不是最初创建的对象。
使用
add_server(server_name, url)
登记 MCP
服务,建立服务别名与 URL 的对应关系。
使用
await add_tool(server_name, func_name)
添加工具。每次只能添加一个工具,没有批量添加接口。
使用
list_tool()
查看已添加的工具,使用
to_openai_tools()
查看最终提供给模型的 OpenAI
格式工具列表。
准备工作: 添加工具前,必须确保对应的 MCP 服务已经启动,因为
add_tool()
需要连接 MCP 服务并获取工具列表。
4.4 添加 Skill
创建
Skill(name, description, content)
对象。
调用用户模型配置的
model_cfg.add_skill(skill)
添加
Skill。该操作会自动将 Skill 复制到用户的
skills/
目录,而模型配置中只记录 Skill 名称。
也可以先通过
skill.save()
将 Skill
保存到全局目录,再供多个用户使用;或者使用
Skill.from_file(path)
导入已有的
SKILL.md
文件。
4.5 一轮对话的完整示例
下面将前面的操作串联起来,演示从创建用户到完成一轮对话的完整流程。
运行前需要准备:
Ollama 已下载
qwen3:8b
模型。
MCP 服务已启动,地址为
http://localhost:8000/mcp
。
MCP 服务中已注册
add
工具。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
import
asyncio
from
cc_agent.agent.agent
import
Agent
from
cc_agent.message.SessionHistory
import
SessionHistory
from
cc_agent.skill
import
Skill
from
cc_agent.users.model_cfg
import
ModelCfg
from
cc_agent.users.user
import
User
USER_NAME =
"demo_user"
CFG_NAME =
"qwen3_8b"
SERVER_NAME =
"local"
MCP_URL =
"http://localhost:8000/mcp"
async
def
main
():
# 1. 创建用户
user = User.create_user(USER_NAME)
# 2. 创建 session 和历史对象
session_id = user.new_session()
history = SessionHistory(USER_NAME, session_id)
# 3. 创建模型配置,添加到用户,再获取用户自己的配置对象
new_cfg = ModelCfg(
CFG_NAME,
model_name=
"qwen3:8b"
,
url=
"http://localhost:11434/v1"
,
type
=
"ollama"
,
)
user.add_model_cfg(new_cfg)
model_cfg = user.get_model_cfg(CFG_NAME)
# 4. 登记 MCP 服务并添加工具
model_cfg.add_server(SERVER_NAME, MCP_URL)
tool_name =
await
model_cfg.add_tool(SERVER_NAME,
"add"
)
# 5. 添加 Skill(自动复制到用户的 skills 目录)
skill = Skill(
"answer-format"
,
"用户要求计算时使用,规定回复的格式"
,
"计算完成后,回复只能写成:计算结果:<数字>"
,
)
model_cfg.add_skill(skill)
# 6. 创建 Agent,必须先完成工具和 Skill 的配置
agent = Agent(history, model_cfg,
"You are a helpful assistant."
)
# 7. 执行一轮对话
reply =
await
agent.generate(
"请用工具计算 123.5 加 876.5"
)
print
(reply)
asyncio.run(main())
一轮对话内部的执行过程:
Agent 将 system prompt(包含 Skill
列表)、
history.messages
(当前窗口内的历史消息)和本次用户输入组合成
OpenAI 格式的消息列表。其中,context 消息(旧消息摘要)会合并到 system
prompt 中;连续的多条
tool_call
消息会合并为一条带有
tool_calls
的 assistant 消息。
Agent 调用模型。如果模型返回了工具调用请求,则进入工具执行流程:
模型可能先调用
load_skill
获取 Skill
的完整内容,也可能直接调用
local__add
等工具。
Agent 通过
run_tool
执行每条工具调用。对于带有
服务别名__
前缀的工具,根据前缀找到对应的 MCP 服务
URL,再通过 MCP Client 执行;对于
load_skill
,则直接返回对应 Skill 的正文。
工具执行结果封装为
tool
消息,追加到本轮消息中,再次发送给模型。
重复上述过程,直到模型返回不包含工具调用的普通回复,作为本轮对话的最终结果。
将本轮缓存的全部消息(用户输入、模型的工具调用、工具执行结果和最终回复)一次性添加到
history
,然后调用
history.save()
保存到 JSONL
文件,最后执行
await history.checkCompact()
,检查是否达到压缩条件。
本轮产生的消息示例:
以下是实际测试中的一次对话记录:
1
2
3
4
5
6
7
===== 对话之后(窗口
6
条)=====
[
seq=
1
]
role=user type=plain content='我是 IT 部门的,电脑坏了,请帮我登记一个报修工单。'
[
seq=
2
]
role=agent type=tool_call content=
{
'name'
:
'load_skill'
,
'arguments'
:
{
'skill_name'
:
'test-ticket-format'
}
call_id=call_lpfdu0d7
[
seq=
3
]
role=tool type=plain content='登记工单时,严格按以下步骤执行:\n1. 先调用 local__get_ticket_id 工具获取工单号,参数 department 填用户所在部门的英文小写缩写(例如 it、hr)。\n2. 拿到工单号后,回复只能用下面这个格式,不要添加任何其他内容:\n工单已登记 | 编号:<工单号> | 处理人:Orion-Desk' call_id=call_lpfdu0d7
[
seq=
4
]
role=agent type=tool_call content=
{
'name'
:
'local__get_ticket_id'
,
'arguments'
:
{
'department'
:
'it'
}
call_id=call_j3sihoj3
[
seq=
5
]
role=tool type=plain content='TICKET-IT
-4821
' call_id=call_j3sihoj3
[
seq=
6
]
role=agent type=plain content='工单已登记 | 编号:TICKET-IT
-4821
| 处理人:Orion-Desk'
4.6 再次使用已有用户和会话
程序重启后,可以通过用户信息和已有的 session ID 恢复之前的对话:
1
2
3
4
5
6
7
8
9
user = User.open_user(
"demo_user"
)
session_ids = user.list_session()
cfg_names = user.list_model_cfg()
history = SessionHistory(
"demo_user"
, session_ids[
0
])
model_cfg = user.get_model_cfg(cfg_names[
0
])
agent = Agent(history, model_cfg,
"You are a helpful assistant."
)
reply =
await
agent.generate(
"我刚才问了什么?"
)
恢复过程:
User.open_user()
打开已有用户。
list_session()
获取该用户的会话 ID 列表。
list_model_cfg()
获取该用户的模型配置名称列表。
SessionHistory()
根据用户名和 session ID
加载对应的历史消息。
get_model_cfg()
获取已有的模型配置。
使用历史对象和模型配置重新创建 Agent,即可继续之前的对话。
需要注意,
SessionHistory
只会加载当前窗口中的消息,即最后一条
context
消息之后的完整消息。模型实际能够看到的是压缩摘要(context)以及摘要之后的完整对话历史。