AI AgentAgent 框架MCP 服务后端【免费下载链接】atomic-agentsBuilding AI agents, atomically项目地址https://gitcode.com/gh_mirrors/at/atomic-agents点击查看免费下载本文以官方示例basic-multimodal为核心系统讲解如何在 Atomic Agents 框架中构建一个「读图 结构化输出」的多模态 Agent将营养成分表图片交给视觉大模型再把识别结果自动转换为严格校验的 Pydantic 模型。读完本文你将掌握多模态输入输出 Schema 的定义方法、AtomicAgent的配置与调用方式、SystemPromptGenerator的提示词编排原理并能把它复用到票据识别、证件解析、单据审核等任意「图像 → 结构化数据」的场景。示例概览多模态 Agent 是如何工作的basic-multimodal是 Atomic Agents 仓库中的一个快速上手示例位于 atomic-examples/basic-multimodal。它演示了框架处理「图片 文本」输入的完整能力核心思路非常清晰图像分析把营养成分表图片交给具备视觉能力的 OpenAI 大模型示例中实际配置为gpt-5-miniREADME 中描述的能力来源即 GPT-4 系列的 Vision 能力结构化数据提取通过 Instructor 框架将模型的自由文本输出约束为预定义的 Pydantic 模型自动完成校验与补全多图并行处理一次请求可同时传入多张营养成分表逐张分析后汇总返回全面营养数据提取包括热量、脂肪、蛋白质等基础营养事实每份/每包装的份量信息维生素与矿物质含量以及产品名称等商品细节。这个示例的深层价值在于它展示了 Atomic Agents 的「零模版」设计理念——你不需要手动拼接 JSON、不需要编写解析正则只需要声明数据结构框架经由 Instructor就会让模型严格按照结构返回数据。环境准备与快速运行第一步获取仓库并进入示例目录git clone https://gitcode.com/gh_mirrors/at/atomic-agents cd atomic-agents/atomic-examples/basic-multimodal第二步使用 uv 安装依赖uv sync项目使用uv作为包管理器依赖声明在 atomic-examples/basic-multimodal/pyproject.toml 中核心依赖如下依赖版本约束作用atomic-agentsworkspace 内部源框架本体提供AtomicAgent、AgentConfig、BaseIOSchemainstructor1.14.5结构化输出引擎提供Image多模态类型与instructor.from_openaiopenai2.0.0,3.0.0OpenAI 官方 Python SDK同时该工程要求requires-python 3.12。注意atomic-agents通过[tool.uv.sources]声明为 workspace 内部依赖这意味着在 monorepo 中执行uv sync时框架会直接与示例一起解析安装无需单独发布。第三步配置 API Key在basic-multimodal目录下创建.env文件OPENAI_API_KEYyour_openai_api_key将your_openai_api_key替换为你的真实 OpenAI API Key。源码 basic_multimodal/main.py 中的读取逻辑是先检查静态变量API_KEY为空则回退到环境变量OPENAI_API_KEY两者都为空时抛出ValueError提示用户配置避免「静默失败」。第四步运行示例uv run python basic_multimodal/main.py程序会打印分析进度然后逐条展示每张图片识别出的结构化营养信息。需要说明的是这是一个同步调用视觉大模型的真实程序运行会产生 API 费用且结果质量取决于模型能力与图片清晰度。源码解剖三大核心组件与实现原理1.NutritionLabel结构化营养数据模型这是整个示例的数据中枢继承自BaseIOSchema其定义在 atomic-agents/atomic_agents/base/base_io_schema.py。BaseIOSchema是 PydanticBaseModel的薄封装额外做了两件事强制 docstring通过__pydantic_init_subclass__校验每个子类必须具有非空 docstring因为该 docstring 会被注入 JSON Schema 的description字段作为模型理解「这个对象是什么」的依据JSON 序列化友好重写__str__与__rich__便于终端直接输出格式化 JSON。NutritionLabel在 main.py 中定义了 19 个字段覆盖宏量营养素、微量营养素、份量信息与产品信息字段类型含义caloriesint每份热量千卡total_fat/saturated_fat/trans_fatfloat总脂肪 / 饱和脂肪 / 反式脂肪克cholesterolint胆固醇毫克sodiumint钠毫克total_carbohydrates/dietary_fiber/total_sugars/added_sugarsfloat总碳水 / 膳食纤维 / 总糖 / 添加糖克proteinfloat蛋白质克vitamin_dfloat维生素 D微克calcium/iron/potassiumint/float/int钙 / 铁 / 钾毫克serving_sizestr单份大小描述如「3 块脆饼28g」servings_per_containerfloat每包装含份数product_namestr产品名称如 Coca Cola Light每个字段都带有Field(..., description...)描述。这不是可选项——描述会进入最终的 JSON Schema 与函数工具定义直接引导模型按正确单位和语义抽取数值例如sodium是毫克而非克。2. 输入/输出 SchemaNutritionAnalysisInput与NutritionAnalysisOutputclass NutritionAnalysisInput(BaseIOSchema): instruction_text: str Field(..., descriptionThe instruction for analyzing the nutrition label) images: List[instructor.Image] Field(..., descriptionThe nutrition label images to analyze) class NutritionAnalysisOutput(BaseIOSchema): analyzed_labels: List[NutritionLabel] Field( ..., descriptionList of nutrition labels extracted from the provided images )输入一条分析指令 一个instructor.Image列表。instructor.Image是 Instructor 提供的多模态类型支持Image.from_path(...)从本地文件加载输出NutritionLabel的列表天然支持「多图 → 多结果」的映射。这正是 Atomic Agents 泛型 Agent 的用法基础Agent 的类型参数决定其输入输出契约。3. Nutrition Analyzer Agent装配与配置Agent 的实例化集中在 main.pynutrition_analyzer AtomicAgentNutritionAnalysisInput, NutritionAnalysisOutput), modelgpt-5-mini, model_api_parameters{reasoning_effort: low}, system_prompt_generatorSystemPromptGenerator( background[...], steps[...], output_instructions[...], ), ) )拆解四个要点a泛型类型参数AtomicAgent[输入Schema, 输出Schema]。AtomicAgent类定义见 atomic-agents/atomic_agents/agents/atomic_agent.py通过__init_subclass__捕获泛型参数并以三级回退机制解析输入/输出 Schema优先类属性继承场景其次实例__orig_class__直接实例化场景最后回退到默认的BasicChatInputSchema/BasicChatOutputSchema。bclient必须是 Instructor 包装过的客户端即instructor.from_openai(openai.OpenAI(...))。这是结构化输出的关键——Instructor 会在请求中加入响应 Schema 约束并把模型返回自动解析、重试为 Pydantic 对象。cmodel_api_parameters示例传入{reasoning_effort: low}属于额外的 API 提供方参数。从源码看它会被原样并入补全请求的 kwargsatomic_agent.py可用于传temperature、max_tokens等任意提供方支持的参数框架还会默认注入strictNone以便遵循 Schema 自身的 Pydantic 行为。dsystem_prompt_generator传入SystemPromptGenerator定义见 atomic-agents/atomic_agents/context/system_prompt_generator.py按background身份与目的、steps内部推理步骤、output_instructions输出指令三段式生成提示词。生成器还会自动追加两条强制输出指令「Always respond using the proper JSON schema.」和「Always use the available additional information and context to enhance the response.」这是保证模型输出符合 Schema 的最后一道提示词约束。最终提示词按# IDENTITY and PURPOSE/# INTERNAL ASSISTANT STEPS/# OUTPUT INSTRUCTIONS三个标题组装。4. 一次调用背后的执行链路调用nutrition_analyzer.run(analysis_request)时框架内部run方法见 atomic_agent.py依次执行_trim_context()若配置了max_context_tokens按轮次裁剪最旧的对话记录以保护新输入把用户输入含图片写入ChatHistory_prepare_messages()生成系统提示词消息 拼接历史self.client.chat.completions.create(messages..., model..., response_modelself.output_schema, ...)携带response_model交给 Instructor 客户端让模型严格按输出 Schema 返回将 Assistant 的响应写入历史并返回。值得注意的是框架还支持run_stream流式部分对象、run_async、run_async_stream三种变体以及基于 Instructor hook 的事件机制如parse:error、completion:kwargs用于监控与错误处理——多模态示例使用的是最直接的同步run路径。运行示例图片加载、分析与结果展示示例自带两张测试图片位于 atomic-examples/basic-multimodal/test_images第一张是经典的美式 Nutrition Facts 版式同时给出每份与整盒两列数值第二张是欧洲常见的三语版式按每 100ml 与每份 200ml 对照展示。两张图片版式差异明显恰好用于验证模型对不同营养标签排版的泛化提取能力。main 函数的流程main.pyscript_directory os.path.dirname(os.path.abspath(__file__)) test_images_directory os.path.join(os.path.dirname(script_directory), test_images) image_path_1 os.path.join(test_images_directory, nutrition_label_1.png) image_path_2 os.path.join(test_images_directory, nutrition_label_2.jpg) analysis_request NutritionAnalysisInput( instruction_textPlease analyze these nutrition labels and extract all nutritional information., images[instructor.Image.from_path(image_path_1), instructor.Image.from_path(image_path_2)], ) analysis_result nutrition_analyzer.run(analysis_request) for i, label in enumerate(analysis_result.analyzed_labels, 1): print(f\nNutrition Label {i}:) print(fProduct Name: {label.product_name}) print(fServing Size: {label.serving_size}) ...三个值得注意的实现细节路径解析不依赖 CWD图片路径基于__file__动态拼接因此无论从哪个目录启动脚本都不会找错图片instructor.Image.from_path把本地图片字节封装为 OpenAI 兼容的image_url内容块随消息一起发送异常处理整个分析过程包在try/except中失败时打印Analysis failed: ...后重新抛出便于定位 API 或校验错误。程序运行结束后控制台会按Nutrition Label 1、Nutrition Label 2的顺序打印每个字段——product_name、serving_size、servings_per_container、calories、各类脂肪、胆固醇、钠、碳水、膳食纤维、糖、蛋白质、维生素 D、钙、铁、钾。所有值均来自模型对图片的 OCR 语义理解并通过 Pydantic 完成类型校验与单位校验。自定义与扩展指南把这个示例迁移到自己的业务场景通常只需改动三处全部集中在main.py零框架改动1. 替换测试图片。把自有图片放入test_images目录并修改main()中的路径变量与images[...]列表即可。多图列表天然支持任意数量的图片无需改其他代码。2. 调整NutritionLabelSchema 以捕捉更多信息。例如为「二维码/条形码编号」「保质期」「过敏原」新增字段class NutritionLabel(BaseIOSchema): ... barcode: str Field(..., descriptionThe barcode number printed on the package) allergens: List[str] Field(..., descriptionAllergens declared on the label)注意三点必须保持 docstring 非空BaseIOSchema强制新增字段必须带 description字段类型决定模型返回的语义——例如用List[str]表达过敏原清单。调整输入 Schema 时同步更新泛型参数AtomicAgent[NutritionAnalysisInput, NutritionAnalysisOutput]即可。3. 修改系统提示词以聚焦特定方面。SystemPromptGenerator的三个列表分别对应「身份定位」「推理步骤」「输出要求」可针对你的场景改写。例如只关心热量和糖分就把steps改为先定位营养表、再只提取目标字段需要多语言时也可在background中声明。若想进一步自动化框架还支持通过register_context_provider注入动态上下文如当前日期、实时数据详见SystemPromptGenerator的context_providers机制。常见问题与注意事项API Key 未配置程序会抛出ValueError: API key is not set...请确认.env中的OPENAI_API_KEY已设置且与 SDK 的环境读取方式一致示例直接使用os.getenv未依赖dotenv自动加载——若.env未生效可先执行export OPENAI_API_KEY...。模型版本与 README 描述README 中将能力来源描述为 GPT-4 Vision而当前仓库代码配置的模型是gpt-5-mini并辅以reasoning_effort: low控制推理成本。二者均为具备视觉能力的多模态模型修改AgentConfig.model字段即可切换到其他 OpenAI 视觉模型。识别精度受图片质量影响模糊、旋转或低分辨率的标签会降低提取准确率多图同时分析时若某张图无效最终列表长度会与图片数不一致可结合product_name等字段核对归属。成本与限流每张图片都会以图片 token 计入请求多图 大模型会产生相应费用高频调用请留意 API 配额。小结basic-multimodal示例完整展示了 Atomic Agents 的核心范式用类型化 Schema 声明输入输出契约用AgentConfig装配模型与提示词用run()一键获得严格校验的结构化结果。它同时覆盖了多模态输入、多图批量处理、Pydantic 结构化校验三个高频需求。无论你要做的是营养标签识别还是发票、合同、检测报告等任何文档类视觉信息抽取这套「声明 Schema 配置 Agent 调用 run」的组合拳都可以直接套用。进一步探索仓库资源框架核心在 atomic-agents/atomic_agents/agents/atomic_agent.pySchema 基类在 atomic-agents/atomic_agents/base/base_io_schema.py提示词生成器在 atomic-agents/atomic_agents/context/system_prompt_generator.py另有 atomic-examples/basic-multimodal/pyproject.toml 可查看完整依赖声明。赞分享AI AgentAgent 框架MCP 服务后端【免费下载链接】atomic-agentsBuilding AI agents, atomically项目地址https://gitcode.com/gh_mirrors/at/atomic-agents点击查看免费下载相关推荐基于 Atomic Agents 与 Gemini 多模态能力的 PDF 结构化文档分析实战基于 Atomic Agents 与 Gemini 多模态能力的 PDF 结构化文档分析实战 导读 本文围绕仓库中 basic pdf analysis httAI AgentAgent 框架MCP 服务后端基于 Atomic Agents 构建 YouTube 知识摘要 Agent从字幕抓取到结构化洞察的完整实战基于 Atomic Agents 构建 YouTube 知识摘要 Agent从字幕抓取到结构化洞察的完整实战 导读 本文围绕 Atomic Agents 仓库AI AgentAgent 框架MCP 服务后端Qwen-Agent Schema 详解基于 Pydantic 的多模态消息、函数调用与推理链数据结构Qwen Agent Schema 详解基于 Pydantic 的多模态消息、函数调用与推理链数据结构 本篇技术指南围绕 Qwen Agent 的消息与数据模人工智能大模型AI AgentAgent 框架工具调用RAG上一篇Source Han Sans TTF高质量Hinting字体构建技术方案下一篇为什么思源黑体TTF是解决多语言字体显示难题的最佳方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考