5.1 KiB
5.1 KiB
测试Agent Steps功能
前置条件
- 运行数据库迁移脚本:
# MySQL
mysql -u user -p database < migrations/mysql/05-add-agent-steps-to-messages.sql
# ParadeDB/PostgreSQL
psql -U user -d database -f migrations/paradedb/05-add-agent-steps-to-messages.sql
- 启动服务器:
./server
测试步骤
1. 创建启用Agent的会话
curl -X POST http://localhost:8080/api/v1/sessions \
-H "Content-Type: application/json" \
-H "X-Tenant-ID: 1" \
-d '{
"knowledge_base_id": "your-kb-id"
}'
2. 发送Agent查询(使用Agent模式)
curl -X POST http://localhost:8080/api/v1/sessions/{session_id}/agent/qa \
-H "Content-Type: application/json" \
-H "X-Tenant-ID: 1" \
-d '{
"query": "帮我搜索关于机器学习的知识"
}'
3. 加载消息历史并检查AgentSteps
curl http://localhost:8080/api/v1/sessions/{session_id}/messages?limit=10 \
-H "X-Tenant-ID: 1"
预期响应格式
{
"success": true,
"data": [
{
"id": "message-uuid",
"session_id": "session-uuid",
"role": "user",
"content": "帮我搜索关于机器学习的知识",
"knowledge_references": [],
"is_completed": true,
"created_at": "2025-10-31T10:00:00Z",
"updated_at": "2025-10-31T10:00:00Z"
},
{
"id": "message-uuid-2",
"session_id": "session-uuid",
"role": "assistant",
"content": "根据搜索结果,机器学习是...",
"knowledge_references": [
{
"id": "chunk-id",
"content": "...",
"score": 0.95,
"knowledge_id": "doc-id",
"knowledge_title": "机器学习基础"
}
],
"agent_steps": [
{
"iteration": 0,
"thought": "用户想了解机器学习,我需要搜索相关知识库",
"tool_calls": [
{
"id": "call_123",
"name": "search_knowledge",
"args": {
"query": "机器学习",
"knowledge_bases": ["kb-id"]
},
"result": {
"success": true,
"output": "找到5个相关文档",
"data": {
"knowledge_refs": [...]
}
},
"duration": 150
}
],
"observations": [
"找到5个相关文档"
],
"timestamp": "2025-10-31T10:00:01Z"
}
],
"is_completed": true,
"created_at": "2025-10-31T10:00:00Z",
"updated_at": "2025-10-31T10:00:02Z"
}
]
}
验证要点
✅ 用户对话历史(Message表)
- assistant消息包含
agent_steps字段 - 每个step包含:
iteration: 迭代次数thought: Agent的思考内容tool_calls: 调用的工具列表observations: 观察结果timestamp: 时间戳
- user消息不包含
agent_steps字段(使用omitempty)
✅ 大模型上下文分离
后续对话时,传给LLM的上下文应该是:
// 只包含简化的Role+Content
[
{"role": "user", "content": "帮我搜索关于机器学习的知识"},
{"role": "assistant", "content": "根据搜索结果,机器学习是..."}
// 不包含agent_steps信息
]
可以通过日志验证:
INFO: Loaded 2 history messages for agent context
✅ 数据库验证
-- 检查agent_steps列
SELECT id, role,
CASE
WHEN agent_steps IS NULL THEN 'NULL'
ELSE JSON_EXTRACT(agent_steps, '$[0].iteration')
END as first_step_iteration
FROM messages
WHERE session_id = 'your-session-id'
ORDER BY created_at DESC;
常见问题
Q1: agent_steps字段为空?
检查:
- Agent模式是否启用(使用
/agent/qa端点) - 数据库迁移是否执行成功
- Handler的事件监听器是否注册
Q2: 上下文是否包含agent_steps?
- 不应该包含!
- 检查
convertMessagesToChatHistory函数 - 确保只使用
Role和Content字段
Q3: 性能影响?
agent_steps使用JSON存储,查询效率高- 前端可以按需展示或折叠步骤详情
- 添加了
idx_messages_session_role索引优化查询
前端集成建议
interface Message {
id: string;
role: 'user' | 'assistant';
content: string;
agent_steps?: AgentStep[]; // 可选字段
knowledge_references?: Reference[];
}
interface AgentStep {
iteration: number;
thought: string;
tool_calls: ToolCall[];
observations: string[];
timestamp: string;
}
// 展示Agent思考过程
function renderAgentSteps(steps: AgentStep[]) {
return steps.map(step => (
<div key={step.iteration}>
<h4>步骤 {step.iteration + 1}</h4>
<p>思考: {step.thought}</p>
<ul>
{step.tool_calls.map(call => (
<li key={call.id}>
调用: {call.name} - {call.result.output}
</li>
))}
</ul>
</div>
));
}
总结
这个实现成功地:
- ✅ 存储了Agent的详细执行步骤
- ✅ 每次任务只记录一个Q和A
- ✅ 分离了用户历史和LLM上下文
- ✅ 避免了上下文重复
- ✅ 保持了向后兼容性