第九章：Agent Protocol Implementation

Chapter 9: Agent Protocol Implementation

---

从工具箱到通用语言：如何让代理与其他系统“对话”？

在上一章依赖管理，我们学会了如何为代理准备好所需的工具库。但就像国际会议需要通用语言一样，代理需要一套“标准化语言”才能与其他程序（如用户界面、测试工具）协作。本章将教你如何通过代理协议实现让不同系统“说同一种语言”！

---

核心使命：为代理打造“通用交流语言”

想象你的代理需要与用户界面和测试工具协同工作：

1. 用户界面想实时获取代理状态
2. 测试工具需要触发基准测试
3. 其他代理想请求帮助处理任务

代理协议就是这套“通用语言”：
✅ 定义所有通信的格式（如JSON）
✅ 规范API端点（如/status获取状态）
✅ 确保不同系统间能无缝交互

---

核心概念拆解：协议的三大支柱

1. 消息格式（标准化语言）

作用：像国际英语，所有系统都能理解
示例格式：

{"type": "status","data": {"running": true,"tasks": 3}
}

2. API端点（交流通道）

作用：像电话号码，定义不同功能的访问路径
端点示例：

端点路径	功能	请求方式
/status	获取代理状态	GET
/run_task	执行任务	POST

3. 协议规范（交流规则）

作用：像交通规则，确保各方遵守
规则示例：

• 必须包含type字段标识消息类型
• 错误必须返回HTTP 500状态码

---

实战演练：创建第一个API端点

目标：让代理对外提供“任务状态查询”功能

我们将实现一个简单的/status端点，返回代理的实时状态。

---

步骤1：定义消息格式

{"type": "status_response","data": {"is_running": true,"current_task": "分析销售数据","progress": 75}
}

步骤2：编写API路由代码

# 来自 app.py 的关键代码片段
from fastapi import FastAPIapp = FastAPI()@app.get("/status")
def get_status():return {"type": "status_response","data": {"is_running": agent.is_running,"current_task": agent.current_task,"progress": agent.progress_percent}}

步骤3：测试API

# 使用curl发送GET请求
curl http://localhost:8000/status

预期响应：

{"type": "status_response","data": {"is_running": true,"current_task": "生成报告图表","progress": 60}
}

---

内部运作：API请求如何被处理？

以获取状态请求为例，流程如下：

关键代码解释（来自 app.py）

# FastAPI自动将函数返回值转为JSON
@app.get("/status")
def get_status():# 直接读取代理的属性return {"type": "status_response","data": agent.get_status()  # 获取当前状态信息}

---

深度解析：协议如何实现互操作性

以代理与测试工具通信为例：

# 测试工具发送POST请求触发任务
curl -X POST -d '{"task": "分析数据"}' http://localhost:8000/run_task# 代理收到请求后执行任务
@app.post("/run_task")
async def run_task(task: str):agent.start_task(task)return {"type": "ack", "message": "任务已开始"}

---

总结与展望

通过本章，你已掌握：
✅ 定义API端点和消息格式
✅ 通过标准化协议实现系统间通信
✅ 用简单示例构建可扩展的交互能力

下一章我们将学习如何将代理与用户界面深度整合——用户界面集成，带你打造直观的代理控制面板！

---