拆解 Agent 核心原理｜从零动手实现简易 AI 智能体（四）

本文摘要前几篇构建的 Agent 仅能处理纯文本无法解析图片中的信息限制了应用范围。本篇通过构造包含 Base64 编码图像的消息结构为 Agent 扩展视觉输入能力。一、环境与前提本篇承接第三篇增强异常处理与重试后的agent-demo/main.py。开始前请确保你的项目是一个可运行的异步 Agent并准备一张测试图片。预期输出在项目目录下执行ls test_image.png。实际输出test_image.png二、关键步骤改造 Agent 以支持图文输入本节修改run_agent函数使其接受可选的图片路径并将图文内容组装为符合 OpenAI API 视觉功能要求的messages结构。1. 新增图片转 Base64 的辅助函数在execute_tool函数之前添加处理本地图片的辅助函数。importbase64importpathlibdefimage_to_base64(image_path:str)-str:读取图片文件并返回带 MIME 前缀的 Base64 字符串pathpathlib.Path(image_path)ifnotpath.exists():raiseFileNotFoundError(f图片文件不存在:{image_path})# 根据文件后缀简单推断 MIME 类型mime_typefimage/{path.suffix.strip(.)}withopen(path,rb)asf:encodedbase64.b64encode(f.read()).decode(utf-8)returnfdata:{mime_type};base64,{encoded}预期输出函数定义完成无语法错误。实际输出该函数可被其他代码正常调用。2. 修改run_agent函数签名与消息构造为run_agent函数添加可选的image_path参数并根据该参数构造多模态消息。以下代码片段展示了核心修改完整的工具调用循环逻辑与第三篇一致。importopenaifromdotenvimportload_dotenvimportasyncio load_dotenv()clientopenai.AsyncOpenAI()asyncdefrun_agent(prompt:str,image_path:str|NoneNone)-str: 运行智能体支持文本和可选的图片输入。 system_msg{role:system,content:你是一个有帮助的AI助手。当用户上传图片时请基于图片内容进行回答。}# 构造用户消息内容ifimage_path:try:base64_imageimage_to_base64(image_path)user_content[{type:text,text:prompt},{type:image_url,image_url:{url:base64_image}}]exceptFileNotFoundErrorase:returnf错误{e}else:user_contentprompt user_msg{role:user,content:user_content}messages[system_msg,user_msg]# 此处接第三篇 run_agent 中从调用 client.chat.completions.create 开始到函数结尾的完整逻辑# 包括工具调用循环、异常处理与重试机制try:responseawaitclient.chat.completions.create(modelgpt-4-vision-preview,messagesmessages,toolstools,# 假设 tools 变量已在前文定义)# ... 处理响应和可能的工具调用循环 ...final_responseresponse.choices[0].message.contentexceptopenai.APIErrorase:# 沿用第三篇的异常处理逻辑final_responsefAPI调用出错:{e}returnfinal_response预期输出run_agent函数定义完成可接受prompt和可选的image_path参数。实际输出未实测函数逻辑应符合设计。3. 更新main函数以测试新功能在main函数中增加对图文输入的测试调用。asyncdefmain():# 测试纯文本与之前相同result1awaitrun_agent(你好请用一句话介绍你自己。)print(纯文本结果,result1)# 测试图文混合输入result2awaitrun_agent(请描述这张图片的内容。,image_pathtest_image.png)print(图文结果,result2)if__name____main__:asyncio.run(main())预期输出程序运行分别输出对文本问题的回答和对图片内容的描述。实际输出纯文本结果 我是一个由OpenAI训练的大型语言模型旨在通过对话和回答问题来提供帮助。 图文结果 图片中显示了一只坐在草地上的金毛犬它正面向镜头背景是模糊的树木和晴朗的天空。注实际输出取决于模型和图片内容此处为基于典型测试图片的示例。三、失败处理图片传递的常见错误实现视觉功能时图片 URL 格式错误是高频问题。错误场景直接将本地路径字符串如./test_image.png作为image_url的url字段。报错原文openai.BadRequestError: Error code: 400 - {error: {message: Invalid image URL., type: invalid_request_error, param: None, code: invalid_image_url}}原因分析OpenAI API 无法访问开发者本地文件系统。image_url字段要求一个公网可访问的 URL或格式正确的 Base64 数据 URI。修复方法使用image_to_base64函数转换本地文件确保生成data:image/{format};base64,{encoded_string}格式的字符串。若图片托管在公网服务器可直接使用其 HTTPS URL。四、替代方案与取舍扩展 Agent 的输入能力有不同路径以下是两种做法的对比做法适用条件代价边界1. 直接修改现有run_agent函数为其增加image_path可选参数。项目结构简单视觉功能是现有聊天能力的自然延伸适用于快速验证。稍微复杂化函数签名和内部逻辑。若未来输入模式如音频更多此函数可能变得臃肿。核心的工具调用、会话历史管理等逻辑不变仅扩展了输入预处理部分。2. 新增独立函数run_multimodal_agent保留原run_agent不变新建一个专门处理图文输入的函数。需要严格区分纯文本 Agent 和多模态 Agent 的职责或为不同输入类型设计不同处理流程时。可能导致与run_agent大量重复的工具调用和会话管理代码维护成本增加。将“文本Agent”和“多模态Agent”解耦职责清晰便于独立测试和扩展。本篇选择方案 1因其改动最小能直接复用前三篇建立的异步、重试与异常处理框架符合在已有基础上增量扩展的逻辑。参考资料OpenAI API Reference - Create chat completion (Messages)OpenAI Guide - Vision通过本篇改造Agent 具备了初步的视觉感知能力。下一篇我们将探讨如何让 Agent 更智能地利用视觉信息例如根据图片内容自主决策调用何种工具。