Agent 智能体开发一Agent 基础与环境准备Hello-Agents GitHubhttps://github.com/datawhalechina/Hello-AgentsHello-Agents Onlinehttps://hello-agents.datawhale.cc一、Agent核心概念LLMLarge Language Model大语言模型本质上是基于Transformer架构的深度神经网络其核心任务是根据输入上下文预测最可能出现词元Token的概率LLM的表现能力本质上源于大规模训练数据集引发的能力涌现量变引起质变。在人工智能领域智能体被定义为任何能够通过传感器Sensors感知其所处环境Environment并自主地通过执行器Actuators采取行动Action以达成特定目标的实体。简单来说LLM是拥有强大自然语言理解能力的“缸中大脑”但其知识是冻结的、静态的而智能体Agent则是在LLM基础上通过工程化技术或框架共同组成具备自主决策和执行能力的动态系统也就是为大脑安装上了“手脚”。智能体的核心运行机制被称为智能体循环Agent Loop即通过持续的循环与交互来完成任务目标该循环主要包括以下几个相互关联的阶段感知Perception感知是循环的起点。智能体通过其传感器例如 API 的监听端口、用户输入等接收来自环境的输入信息。这些信息即观察 (Observation)既可以是用户的初始指令、也可以是上一步行动所导致的环境状态变化反馈。思考Thought接收到观察信息后智能体进入其思考与决策阶段。对于 LLM 智能体而言这通常是由大语言模型驱动的内部推理过程该过程包括规划计划制定、任务拆解与工具选择选择工具、确定参数两个关键环节需要注意的是记忆与反思也可纳入工具选择的范畴。行动Action决策完成后智能体通过其执行器Actuators执行具体的行动。这通常表现为调用一个选定的工具如代码解释器、搜索引擎 API等从而对环境施加影响、改变环境的状态。智能体通过智能体循环形成一个持续的“感知-思考-行动”的闭环从“生成答案”向“生成状态序列”转变运行机制的循环示意图如下所示二、OpenAI 规范官方API文档https://platform.openai.com/docs/api-reference官方OpenAPI文档https://github.com/openai/openai-openapiOpenAI接口规范是由OpenAI官方发布的一套标准化RESTful API 接口定义允许客户端通过HTTP协议与大语言模型如 GPT 系列服务进行交互。由于其在业界广泛采用许多模型服务商包括 OpenAI、Azure、DeepSeek、GLM 以及众多开源模型服务框架如 Ollama、vLLM 等也都纷纷兼容该规范使得它逐渐成为 LLM 行业的标准接口格式。OpenAI接口规范的内容主要包括以下维度统一的路由端点定义接口端点规范化比如对话补全/v1/chat/completions、文本嵌入/v1/embeddings、模型列表v1/models等标准化的请求结构和响应格式接口均通过请求头Authorization: Bearer API_KEY进行认证且请求和响应均使用JSON结构化数据其中请求参数包括模型model、消息messages、控制参数如temperature等标准内容响应数据则包含生成内容choices、统计用量usage等关键对象支持流式输出规范当请求参数存在streamtrue时服务端采用Server-Sent Events (SSE)协议持续返回数据并使用特殊标识标记流式传输结束跨平台兼容能力OpenAI接口规范使用OpenAPI规范编写支持YAML或JSON格式与各种编程语言和平台兼容。OpenAPI规范OpenAPI Specification是一种与编程语言无关的、标准化的 RESTful API 描述格式用于定义、描述和文档化 HTTP API 接口它的前身是 Swagger 规范OpenAI规范的实现本质上是套C/S客户端服务端架构服务端的核心职责包括请求参数解析、执行推理引擎调用模型以及响应结果拼装而客户端则负责参数格式化和服务端请求。以对话补全接口/v1/chat/completions为例OpenAI标准化请求与响应的curl格式如下requestcurlhttps://api.openai.com/v1/chat/completions\-HContent-Type: application/json\-HAuthorization: Bearer$OPENAI_API_KEY\-d{ model: VAR_chat_model_id, messages: [ { role: developer, content: You are a helpful assistant. }, { role: user, content: Hello! } ] }response{id:chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT,object:chat.completion,created:1741569952,model:gpt-5.4,choices:[// 生成内容数据{index:0,message:{role:assistant,content:Hello! How can I assist you today?,refusal:null,annotations:[]},logprobs:null,finish_reason:stop}],usage:{// 用量统计数据prompt_tokens:19,completion_tokens:10,total_tokens:29,prompt_tokens_details:{cached_tokens:0,audio_tokens:0},completion_tokens_details:{reasoning_tokens:0,audio_tokens:0,accepted_prediction_tokens:0,rejected_prediction_tokens:0}},service_tier:default}三、环境准备1. Python 要求1.1 版本要求Python 3.10推荐使用 Python 3.10 或更高版本支持的操作系统Windows、macOS、Linux1.2 依赖要求pipinstallrequests2.31.0# HTTP客户端库pipinstallopenai1.0.0# OpenAI Python SDKOpenAI接口规范官方客户端pipinstallpython-dotenv1.0.0# 从 .env 文件加载环境变量到 Python 进程中避免敏感配置硬编码pipinstallgoogle-search-results# SerpApi Python SDK提供结构化的Google搜索结果的Web搜索工具2. API 配置2.1 大语言模型服务APIModelScope 是国内领先的 AI 模型聚合平台平台提供免费模型和免费额度能够满足我们的实践需求访问官网 ModelScope注册成功后需绑定阿里云账号可以在设置界面获取API访问令牌并在模型库查看所有可用的推理 API-Inference建议选择兼容 OpenAI 格式的免费模型模型随时可能上线或下线。2.2 网页搜索工具 SerpAPISerpAPI 是一个搜索引擎结果 API 服务它通过 API 调用查询结果并返回结构化数据除了支持 Google 外它还支持 Bing、Baidu 等其它搜索引擎访问官网SerpApi: Google Search API注册免费帐户每月250次免费搜索额度并获取账号的API密钥Key我们需要将密钥添加到环境配置文件.env中在DOCUMENTATION中我们可以找到各搜索引擎的API说明建议 Google。3. 参数配置在项目根目录下创建名为.env的环境配置文件代码将通过load_dotenv()从此文件自动加载关键配置。# .env file# ModelScopeLLM_API_KEYMODELSCOPE_ACCESS_TOKENLLM_MODEL_IDMODEL_IDLLM_BASE_URLhttps://api-inference.modelscope.cn/v1# SerpAPISERPAPI_API_KEYYOUR_SERPAPI_API_KEY四、基础封装1. LLM调用客户端封装基于OpenAI客户端封装专属的LLM客户端类目的是屏蔽所有与模型服务交互的细节importosfromtypingimportList,Dict,OptionalfromopenaiimportOpenAIclassBaseAgentClient: LLM 客户端 它用于调用任何兼容OpenAI接口规范的服务 def__init__(self,model:strNone,apiKey:strNone,baseUrl:strNone,timeout:intNone): 初始化客户端优先使用传入参数如果未提供则从环境变量加载 self.modelmodeloros.getenv(LLM_MODEL_ID)apiKeyapiKeyoros.getenv(LLM_API_KEY)# 不保存敏感配置信息仅用于创建客户端baseUrlbaseUrloros.getenv(LLM_BASE_URL)timeouttimeoutorint(os.getenv(LLM_TIMEOUT,60))# 任意配置为空则抛出异常ifnotall([self.model,apiKey,baseUrl]):raiseValueError(参数异常模型ID、API密钥或服务地址未定义)# 创建 OpenAI 接口规范客户端self.clientOpenAI(api_keyapiKey,base_urlbaseUrl,timeouttimeout)defthink(self,messages:List[Dict[str,str]],temperature:float0)-Optional[str]: 调用大语言模型思考并返回标准化响应 print(f 正在调用{self.model}模型...)try:# 获取模型响应默认非流式responseself.client.chat.completions.create(modelself.model,messagesmessages,temperaturetemperature,streamFalse)# 处理模型响应resultresponse.choices[0].message.contentprint(f✅ 大语言模型响应成功: \n{result})returnresultexceptExceptionase:print(f❌ 大语言模型响应失败:{e})returnNone2. 测试验证非流式的交互方式等待模型服务响应时间较长最好将参数timeout设置的大点否则容易超时。fromclient.BaseAgentClientimportBaseAgentClientfromdotenvimportload_dotenv# 加载 .env 文件中的环境变量配置load_dotenv()defagent_client_run():agentClientBaseAgentClient()exampleMessages[{role:system,content:You are a helpful assistant that writes Python code.},{role:user,content:简单概括什么是双向循环链表}]print(--- 调用LLM ---)responseTextagentClient.think(exampleMessages)ifresponseText:print(\n\n--- 完整模型响应 ---)print(responseText)if__name____main__:agent_client_run()--- 调用LLM --- 正在调用 coding-glm-5.1-free 模型... ✅ 大语言模型响应成功: 简单来说**双向循环链表**是一种特殊的链表数据结构它的核心特征可以概括为两个词**双向** 和 **循环**。 具体表现如下 1. **双向**链表中的每个节点都包含三个部分 * 数据域存放数据 * 前驱指针prev指向上一个节点 * 后继指针next指向下一个节点 * *好处不仅可以向后遍历还可以向前遍历操作非常灵活。* 2. **循环**链表的首尾相连没有明显的边界没有传统意义上的 NULL 或 None 结尾 * **头节点**的 prev 指针指向**尾节点**。 * **尾节点**的 next 指针指向**头节点**。 * *好处从任何一个节点出发都可以不断循环访问到链表中的所有其他节点。* **形象的记忆法** 就像一伙人手拉手围成一个圈每个人既能看到自己左边的人前驱也能看到自己右边的人后继。无论从哪个人开始顺时针或逆时针走最终都能走回原点并经过所有人。 --- 完整模型响应 --- 简单来说**双向循环链表**是一种特殊的链表数据结构它的核心特征可以概括为两个词**双向** 和 **循环**。 具体表现如下 1. **双向**链表中的每个节点都包含三个部分 * 数据域存放数据 * 前驱指针prev指向上一个节点 * 后继指针next指向下一个节点 * *好处不仅可以向后遍历还可以向前遍历操作非常灵活。* 2. **循环**链表的首尾相连没有明显的边界没有传统意义上的 NULL 或 None 结尾 * **头节点**的 prev 指针指向**尾节点**。 * **尾节点**的 next 指针指向**头节点**。 * *好处从任何一个节点出发都可以不断循环访问到链表中的所有其他节点。* **形象的记忆法** 就像一伙人手拉手围成一个圈每个人既能看到自己左边的人前驱也能看到自己右边的人后继。无论从哪个人开始顺时针或逆时针走最终都能走回原点并经过所有人。