文章目录【69.PythonAI】OpenAI Assistants API零框架成本的官方Agent开发方案导入语1 ~ Assistants API 的三件套1.1 Assistant / Thread / Run2 ~ 三大内置工具2.1 Code Interpreter代码解释器2.2 File Search文件检索2.3 Function Calling3 ~ Run 的状态管理3.1 Run 的生命周期3.2 处理 requires_action4 ~ 完整案例Excel 数据分析 PPT 大纲生成4.1 需求4.2 实现5 ~ 自己写 Agent vs 用 Assistants API选型建议思考 总结结尾【69.PythonAI】OpenAI Assistants API零框架成本的官方Agent开发方案文章简介本文系统讲解OpenAI Assistants API——这是一个不用自己写Agent框架、直接调用官方API就能实现Agent功能的服务。文章拆解Assistants API的三件套Assistant/Thread/Run的各自职责和协作方式Assistant定义角色和工具、Thread管理对话上下文、Run驱动执行循环。重点讲解三大内置工具Code Interpreter代码解释器、File Search文件检索、Function Calling函数调用的使用方法和各自的能力边界。最后实现一个自动分析Excel数据并生成PPT大纲的完整案例配以Mermaid时序图展示Assistant/Thread/Run的协作流程。适合想用最少代码快速落地Agent功能的开发者。 个人主页源码骑士❄专栏传送门《Android开发基础》《python基础课程》⭐️热衷从源码视角拆解技术底层原理将复杂架构讲得通俗易懂 源码骑士的简介5年Android Framework系统开发经验曾主导多项系统级性能优化专项技术栈覆盖Android系统全链路Binder/Handler/AMS/WMS/启动流程及Java后端全家桶Spring MyBatis Redis Oracle累计产出原创技术文章100篇文章以流程图为特色被读者评价为看一篇胜过啃一周源码导入语前面几篇文章我们自己手写了 ReAct Agent、Plan-Execute Agent从 Prompt 设计到工具解析到执行循环——每一步都是自己写的。但 OpenAI 其实已经给你封装好了一套现成的 Agent 方案——Assistants API。你不用写执行循环、不用管上下文管理、不用自己实现代码执行器——调几个 API 就完事了。它的缺点也很明显贵、被锁死在 OpenAI 生态、定制化空间有限。这篇文章就把 Assistants API 的核心玩法讲清楚。看完之后你能判断一个项目是该自己写 Agent 还是直接用 Assistants API。1 ~ Assistants API 的三件套1.1 Assistant / Thread / RunThreadAssistantOpenAI API开发者ThreadAssistantOpenAI API开发者1. 创建 Assistant\n(定义角色、工具、模型)2. 创建 Thread\n(对话容器)3. 添加用户消息到 Thread4. 创建 Run\n(启动执行)5. Assistant 读取 Thread 中的消息6. 决定是否需要调工具7. 如果需要 → 请求执行工具8. 返回 required_action9. 提交工具执行结果10. Assistant 继续推理11. 写入最终回复12. 读取 Thread 中的最新消息概念是什么类比Assistant定义AI的角色、使用的模型、拥有的工具一个员工的岗位说明书Thread一个对话的容器存所有消息一个聊天窗口Run一次执行——Assistant读取Thread、思考、可能调用工具员工开始处理一个任务2 ~ 三大内置工具2.1 Code Interpreter代码解释器最强大的内置工具——给 Assistant 一个沙箱 Python 环境它可以写代码、执行、返回结果fromopenaiimportOpenAI clientOpenAI()# 创建带 Code Interpreter 的 Assistantassistantclient.beta.assistants.create(name数据分析师,instructions你是一个数据分析专家擅长处理Excel和CSV数据,modelgpt-4-turbo,tools[{type:code_interpreter}],# 开启代码解释器)# 上传文件fileclient.files.create(fileopen(sales_data.csv,rb),purposeassistants)# 创建 Thread 并发消息threadclient.beta.threads.create()client.beta.threads.messages.create(thread_idthread.id,roleuser,content分析这个销售数据找出销售额最高的月份画一个趋势图,attachments[{file_id:file.id,tools:[{type:code_interpreter}]}])# 执行runclient.beta.threads.runs.create_and_poll(thread_idthread.id,assistant_idassistant.id,)Code Interpreter 能做什么能力例子数据分析读取CSV/Excel统计、聚合、可视化数学计算复杂公式求值文件生成生成图表、处理后的数据文件图像处理读取图片文件进行分析2.2 File Search文件检索给 Assistant 上传文档它自动做向量化并支持语义搜索——本质上是一个内置的 RAG# 创建带 File Search 的 Assistantassistantclient.beta.assistants.create(name知识库助手,instructions基于上传的文档回答问题,modelgpt-4-turbo,tools[{type:file_search}],)# 创建向量存储vector_storeclient.beta.vector_stores.create(name公司文档)# 上传文件到向量存储file_batchclient.beta.vector_stores.file_batches.upload_and_poll(vector_store_idvector_store.id,files[open(policy.pdf,rb),open(manual.pdf,rb)])# 关联到 Assistantassistantclient.beta.assistants.update(assistant_idassistant.id,tool_resources{file_search:{vector_store_ids:[vector_store.id]}},)2.3 Function Calling和标准 Chat Completions 的 Function Calling 一样——自定义你的函数让 Assistant 调用assistantclient.beta.assistants.create(name天气助手,modelgpt-4-turbo,tools[{type:function,function:{name:get_weather,description:获取指定城市的天气信息,parameters:{type:object,properties:{city:{type:string,description:城市名如北京}},required:[city]}}}])3 ~ Run 的状态管理3.1 Run 的生命周期queued → in_progress → requires_action → in_progress → completed ↑ │ └──────────────────────────┘(提交工具结果后继续)3.2 处理 requires_action当 Assistant 需要调用自定义函数时Run 的状态变为requires_actiondefhandle_run(run,thread_id):轮询处理 Run直到完成whilerun.statusin[queued,in_progress]:runclient.beta.threads.runs.retrieve(thread_idthread_id,run_idrun.id)ifrun.statusrequires_action:# 获取需要调用的工具tool_callsrun.required_action.submit_tool_outputs.tool_calls tool_outputs[]fortool_callintool_calls:func_nametool_call.function.name func_argsjson.loads(tool_call.function.arguments)# 执行对应的函数iffunc_nameget_weather:resultget_weather(func_args[city])tool_outputs.append({tool_call_id:tool_call.id,output:str(result)})# 提交工具执行结果runclient.beta.threads.runs.submit_tool_outputs_and_poll(thread_idthread_id,run_idrun.id,tool_outputstool_outputs)# 读取最终回复ifrun.statuscompleted:messagesclient.beta.threads.messages.list(thread_idthread_id)returnmessages.data[0].content[0].text.value4 ~ 完整案例Excel 数据分析 PPT 大纲生成4.1 需求用户上传一个销售Excel文件Assistant 分析数据、找出关键指标、生成一份PPT大纲。4.2 实现defanalyze_excel_and_create_outline(excel_file_path:str):完整流程上传→分析→生成大纲# 1. 上传文件fileclient.files.create(fileopen(excel_file_path,rb),purposeassistants)# 2. 创建 AssistantCode Interpreterassistantclient.beta.assistants.create(name数据分析与报告助手,instructions你是一个数据分析专家。流程如下 1. 读取上传的Excel文件分析数据 2. 计算关键指标总和、平均值、趋势 3. 生成一份适合做PPT的大纲 大纲格式每页标题 3个要点 建议的图表类型,modelgpt-4-turbo,tools[{type:code_interpreter}],)# 3. 创建 Threadthreadclient.beta.threads.create()# 4. 发消息client.beta.threads.messages.create(thread_idthread.id,roleuser,content(分析上传的销售数据文件回答\n1. 总销售额是多少\n2. 各季度的销售趋势\n3. 哪个产品线表现最好\n4. 生成一份10页以内的PPT大纲),attachments[{file_id:file.id,tools:[{type:code_interpreter}]}])# 5. 创建并等待 Runrunclient.beta.threads.runs.create_and_poll(thread_idthread.id,assistant_idassistant.id,)# 6. 获取结果messagesclient.beta.threads.messages.list(thread_idthread.id)returnmessages.data[0].content[0].text.value5 ~ 自己写 Agent vs 用 Assistants API对比维度自己写 AgentAssistants API开发成本高Prompt设计工具解析循环低几行API调用运行费用按 LLM 调用量按 LLM 调用量 文件存储费工具能力任意扩展三大内置工具 Function Calling上下文管理需自己实现 Token 预算自动管理无限制上下文供应商锁定无完全绑定 OpenAI调试能力每步可见黑盒只能看最终结果数据安全数据不出自己服务器数据上传到 OpenAI选型建议用 Assistants API 如果 ✅ 快速原型验证 ✅ 数据不敏感 ✅ 不需要复杂定制 ✅ 团队没有Agent开发经验 自己写 Agent 如果 ✅ 需要完全控制执行流程 ✅ 数据不能出内网 ✅ 需要非OpenAI的LLM ✅ 需要自定义检索策略思考 总结Assistants API 是把 LangChain LlamaIndex 的活内置到了 OpenAI 服务里你不需要引入任何框架调 API 就能实现 RAG、代码执行、Function Calling。Code Interpreter 是最大的亮点一个安全沙箱 在线 Python 运行环境让 Agent 自己写代码分析数据——这个能力自己实现要写很多安全代码。Thread 的无限上下文是一个隐藏福利你自己写 Agent 要考虑 Token 超出问题Assistants API 帮你全自动管理了。缺点同样明显贵文件存储也要钱、不透明看不到中间推理过程、锁定只能用OpenAI模型。最务实的用法原型用 Assistants API 快速验证 → 产品用自研 Agent 上线。前者让你一周就跑通概念后者给你长期的控制力。Assistants API 是一个用钱换时间的方案。如果你今天就要Demo、下个月才考虑规模化先上 API再考虑自研。结尾各位小伙伴本文的内容到这里就全部结束了源码骑士在这里再次感谢您的阅读源码骑士 — Android Framework 全栈开发关注跟博主一起从源码视角深耕底层原理见证每一次成长❤️点赞让优质内容被更多人看见让知识传递更有力量⭐收藏把核心知识点存好在需要时随时查、随时用评论分享你的经验或疑问评论区一起交流避坑一键四连不要忘记给博主一键四连哦️寄语技术之路难免有困惑但同行的人会让前进更有方向结语会用框架是入门知道什么时候不该用框架是进阶。Assistants API 让你以最低的成本体验 Agent 开发的完整链路——跑通之后你会更清楚地知道哪些环节值得自研、哪些直接调 API 就够了。不要忘记给博主一键四连哦