agno Agent 输入输出实战：9 个示例与 3 条结构化路径

agno Agent 输入输出实战9 个示例与 3 条结构化路径【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno用 agno 构建 Agent智能体时模型回复常常不可用形态漂移、字段无法解析、结果只停留在控制台。本文基于cookbook/02_agents/02_input_output/目录下 9 个已验证示例讲透输入侧契约、输出侧结构化路径与运行侧捕获落盘。读完即可独立完成 Agent 的输入校验与结构化输出接入。能力全景9 个示例按输入 / 输出 / 运行三侧分组侧能力点一句话价值示例文件输入侧expected_output用自然语言约束回复成品形态expected_output.py输入侧结构化消息输入程序侧传图文混合的字典input_formats.py输入侧input_schema用 Pydantic 模型做输入校验input_schema.py输出侧output_schemarun.content直接成为结构化对象output_schema.py输出侧parser_model独立第二模型完成结构化抽取parser_model.py输出侧output_model用第二模型替换主模型输出做精修output_model.py运行侧run()/RunOutput把响应捕获为可程序化消费的变量response_as_variable.py运行侧save_response_to_file每次运行后自动保存响应文件save_to_file.py运行侧streamTrue逐 token 流式输出streaming.py9 个文件均位于 cookbook/02_agents/02_input_output/。据 TEST_LOG.md测试日期 2026-02-13环境为.venvs/demo/bin/pythonpgvector 服务运行中9/9 全部 PASS ✅单次耗时 2s–101s。其中input_schema.py最高101s含 HackerNews 工具真实调用的多轮推理input_formats.py最低2s仅单次生成。仓库测试目录自带图片资源上面的相对路径素材即可作为 Agent 图片输入使用正文示例则演示了直接传图片 URL 的方式。场景一如何约束回复形态并校验结构化输入不加约束时Agent 回复形态随机输入侧也无法保证字段齐整。agno 用两个参数分别处理软约束和硬契约。expected_output不是行为规则而是对回复成品的规格说明。源码 agent.py L255 声明为Optional[str] None默认不启用。input_schema在 L303 声明为Optional[Type[BaseModel]]只接受 Pydantic 模型类不支持裸字典。# expected_output.py用自然语言指定回复形态 agent Agent( modelOpenAIResponses(idgpt-5.2), expected_outputA numbered list of exactly 5 items, each with a title and one-sentence description., markdownTrue, ) agent.print_response(What are the most important principles of clean code?, streamTrue) # input_schema.pyPydantic 模型定义输入契约 class ResearchTopic(BaseModel): topic: str focus_areas: List[str] Field(descriptionSpecific areas to focus on) target_audience: str sources_required: int Field(default5) hackernews_agent Agent( modelOpenAIResponses(idgpt-5-mini), tools[HackerNewsTools()], input_schemaResearchTopic, ) # 两种输入形式都支持字典 或 Pydantic 实例 hackernews_agent.print_response(input{topic: AI, focus_areas: [AI], target_audience: Developers, sources_required: 5}) hackernews_agent.print_response(inputResearchTopic(topicAI, focus_areas[AI], target_audienceDevelopers, sources_required5))expected_output只管答案长什么样适合约束条数、字段、编号等形态实测 4s 完成不改变运行链路。input_schema是硬契约示例中 int 字段传字符串5仍通过校验依赖 Pydantic 宽松转换101s PASS。多模态输入无需任何参数print_response直接接受{role: user, content: [文本段, image_url 段]}的消息字典实测仅 2s。选型形态软约束用expected_output字段硬校验用input_schema图文混合直接传消息字典。输入侧定完更常见的需求是让输出变成可解析的结构。场景二结构化输出的 3 条路径如何选下游程序要直接消费字段自然语言无法解析。agno 提供三条路径全部声明在同一源码文件中output_schemaL306类型为Optional[Union[Type[BaseModel], Dict[str, Any]]]Pydantic 类或 JSON Schema 字典均可parser_modelL308把抽取交给独立模型调用output_modelL312配合output_model_promptL314用第二模型替换主模型输出。# output_schema.py主模型直接按契约输出单次链路 class BreakingNewsSummary(BaseModel): topic: str summary: str key_updates: List[str] overall_sentiment: str agent Agent(modelOpenAIResponses(idgpt-5.2), output_schemaBreakingNewsSummary) run: RunOutput agent.run(Latest news from France?) pprint(run.content) # 直接是 BreakingNewsSummary 实例 # parser_model.py主模型推理第二模型负责抽取结构 agent Agent( modelOpenAIResponses(idgpt-5.2), output_schemaNationalParkAdventure, # 11 个字段含 ge1, le5 数值约束 parser_modelOpenAIResponses(idgpt-5.2), )结构化抽取的原始对象常是上这类非结构化文档07_knowledge目录即提供此类测试资源。output_schema是默认路径主模型直出链路最短实测 18s。parser_model分离推理与结构适合主模型带工具或格式遵循不稳的场景实测 46s。output_model只做自然语言精修实测 49s文件头注释明确提示结构化 JSON 请改用parser_model。路径实测耗时何时用output_schema18s单模型、格式遵循稳定output_schema parser_model46s主模型输出不可控或结构复杂output_model49s最终回复需要文字精修、非结构化输出形态确定后接下来看响应在运行时的捕获与持久化。场景三响应如何捕获为变量、流式输出并自动落盘print_response只负责展示程序无法继续消费结果也不留痕。agent.run()返回RunOutput对象可整体捕获追加streamTrue则返回Iterator[RunOutputEvent]可逐事件处理save_response_to_fileL323让每次运行后自动写入指定文件。# response_as_variable.py捕获响应为变量 run_response: RunOutput agent.run(What is the stock price of NVDA) pprint(run_response) # 流式变体原注释保留 # run_response_stream: Iterator[RunOutputEvent] agent.run(..., streamTrue) # save_to_file.py每次运行后自动落盘 agent Agent( modelOpenAIResponses(idgpt-5.2), save_response_to_filetmp/agent_output.md, ) os.makedirs(tmp, exist_okTrue) # 父目录需自行创建 agent.print_response(Write a brief guide on Python virtual environments., streamTrue)run()与print_response()是同一条链路前者返回可消费对象实测 12s后者面向交互式富文本展示。流式只差一个参数print_response(..., streamTrue)即逐 token 输出实测 9s。落盘目录不会自动创建示例显式os.makedirs这是该参数最容易忽略的前置步骤实测 10s。选型交互式演示用print_response程序化流程、指标采集用run需要归档时叠加save_response_to_file。横向对比与选型指南所有参数默认均为None声明位置集中在 agent.py L255–L323。参数源码类型默认值作用适用场景expected_outputOptional[str]None自然语言描述回复形态条数 / 编号 / 结构等格式约束input_schemaOptional[Type[BaseModel]]None输入须符合该 Pydantic 模型结构化输入契约output_schemaOptional[Union[Type[BaseModel], Dict[str, Any]]]None输出直接成为结构化对象JSON 字段消费parser_modelOptional[Model]None独立模型做结构化抽取主模型格式遵循弱output_modelOptional[Model]None替换主模型输出做精修成本与质量平衡output_model_promptOptional[str]None精修模型的改写指令文案 / 风格定制save_response_to_fileOptional[str]None响应自动写入文件结果归档选型建议如果你的需求是下游直接消费字段优先选output_schema因为主模型按契约直出、链路调用最少18s vs 46s。如果你的需求是主模型带工具或输出不稳定优先选output_schema parser_model因为结构由第二次独立调用兜底与主模型能力解耦。如果你的需求是便宜模型推理、最终稿要精修优先选output_model因为主模型负责推理与工具调用强模型只替换最终输出实测 49s。边界说明与常见误区⚠️save_response_to_file的目录不会自动创建写入会直接失败。先执行os.makedirs(..., exist_okTrue)再运行。input_schema不接受裸字典定义只能传 Pydantic 模型类字典只是输入值的兼容形式且不要依赖隐式类型转换如5→int。耗时数据仅作相对参考来自 2026-02-13 单次实测.venvs/demo/bin/python pgvector依赖具体模型与网络状态不应视为性能承诺。不要用output_model做 JSON它面向自然语言精修结构化输出应走parser_model文件头注释已明确区分二者。相邻能力followups/num_followupsL327 / L329默认 3 条可生成追问建议示例见 cookbook/02_agents/02_input_output/ 的followup_suggestions.py输入输出类型化另有 cookbook/00_quickstart/ 的agent_with_typed_input_output.py。小结区分输入 / 输出 / 运行三侧参数用expected_output约束回复形态用input_schema定义输入契约结构化输出三路径按需选一响应可捕获、可流式、可落盘按 README.md 完成direnv allow与./scripts/demo_setup.sh后执行.venvs/demo/bin/python cookbook/02_agents/02_input_output/streaming.py即可开始复现全部链路。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考