agno Agent 输入输出完整指南：9 个实战示例讲透结构化输入输出

agno Agent 输入输出完整指南：9 个实战示例讲透结构化输入输出

【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno

本文以 agno 的 9 个官方示例为线索，一次讲清 agno Agent 输入输出机制：如何用 expected_output 与 input_schema 约束输入，如何用 agno 结构化输出参数 output_schema、parser_model、output_model 管住答案，外加流式输出、变量捕获与响应落盘三种运行方式。

先说问题：Agent 的输入输出到底失控在哪

把 Agent 用到生产链路里，通常会撞上四堵墙：

• 回复格式不可控：要求"恰好 5 条编号列表"，模型回了一段自由散文，下游展示层没法渲染；
• 输出无法结构化：run.content是一段字符串，后续代码想取"主题""情感倾向"这些字段只能再写正则硬解析；
• 成本与质量难兼得：全程用旗舰模型账单扛不住，换小模型产出又得人工返工；
• 输入自由度过高：一个调研任务只传一句自然语言，模型只能靠猜来理解范围与受众。

好消息是，agno 把解法都收敛到了Agent构造器的少数几个字段上（源码位于libs/agno/agno/agent/agent.py）。cookbook/02_agents/02_input_output/目录下的 9 个示例在 2026-02-13 的测试中全部 PASS（untagged 层级），本文按"输入 → 输出 → 运行"的顺序把它们重新组织了一遍。

先跑起来：环境准备与单文件运行方式

按目录 README 的前置步骤操作即可：

1. 用direnv allow加载环境变量（包含OPENAI_API_KEY）；
2. 执行./scripts/demo_setup.sh创建 demo 虚拟环境；
3. 单文件运行命令：

.venvs/demo/bin/python cookbook/02_agents/02_input_output/<file>.py

4. 个别示例依赖可选的本地服务（如 pgvector）或特定服务商的 API key，按需准备。

本文引用的基线数据来自同目录的TEST_LOG.md：测试日期 2026-02-13，环境.venvs/demo/bin/python，pgvector 处于运行状态，9 个示例状态均为 PASS。

输入侧：三种约束 Agent 输入的方法 🔍

按"提示词级 → 消息级 → 契约级"由浅入深，对应expected_output、消息字典输入、input_schema三个手段。

expected_output：告诉模型"答案该长什么样"

expected_output给 Agent 一个回复成品的形态规格（源码 agent.py L252，声明为Optional[str]，默认None）。它和instructions的分工不同：instructions管行为规则，这个字段只管"成品长什么样"。

agent = Agent( model=OpenAIResponses(id="gpt-5.2"), expected_output="A numbered list of exactly 5 items, each with a title and one-sentence description.", markdown=True, ) agent.print_response("What are the most important principles of clean code?", stream=True)

易踩坑点：描述越具体（条数、是否带标题），遵循率越高。实测该示例 4s PASS，单次生成链路无任何额外调用，只有回复形态被约束。

消息字典输入：文本和图片一起传

print_response的入参不局限于字符串，也可以传role+content列表的消息字典，从而在程序侧直接拼装图文混合内容：

agent.print_response( { "role": "user", "content": [ {"type": "text", "text": "What's in this image?"}, {"type": "image_url", "image_url": {"url": "<图片 URL>"}}, ], }, stream=True, markdown=True, )

细节：示例里的Agent()甚至没有显式传 model，说明结构化消息在解析层几乎零成本。实测 2s PASS，是全套件耗时最短的一个。

input_schema：用 Pydantic 模型给输入上契约

源码声明input_schema: Optional[Type[BaseModel]]（agent.py L300）：只接受 Pydantic 模型类，不支持裸字典定义；运行时既可以传符合 schema 的字典，也可以直接传模型实例。

class ResearchTopic(BaseModel): topic: str focus_areas: List[str] target_audience: str sources_required: int = 5 agent = Agent( model=OpenAIResponses(id="gpt-5-mini"), tools=[HackerNewsTools()], input_schema=ResearchTopic, ) agent.print_response(input={"topic": "AI", "focus_areas": ["AI", "Machine Learning"], "target_audience": "Developers", "sources_required": "5"})

易踩坑点：字典写法里sources_required传的是字符串"5"，字段类型却是int——靠 Pydantic 的宽松类型转换兜住了。实测 101s PASS，全套件最慢：因为挂了HackerNewsTools，Agent 会发起真实工具检索，是多轮推理而非单次生成。

输出侧：agno 结构化输出的三条路径 ⚖️

output_schema 用法：让模型直接吐出结构化对象

output_schema: Optional[Union[Type[BaseModel], Dict[str, Any]]]（agent.py L303），即 Pydantic 模型类与 JSON Schema 字典两种写法都认。

class BreakingNewsSummary(BaseModel): topic: str summary: str key_updates: List[str] overall_sentiment: str agent = Agent( model=OpenAIResponses(id="gpt-5.2"), output_schema=BreakingNewsSummary, ) run: RunOutput = agent.run("Latest news from France?") pprint(run.content)

跑完后run.content就是符合模型的实例，按字段取用、不用二次解析。实测 18s PASS，是输出侧三条路径里链路最轻的一条。

output_schema 与 parser_model 怎么选：把抽取交给第二个模型

parser_model: Optional[Model]（agent.py L305，默认None）改变的是分工：主模型照常推理、照常调用工具，输出不受结构约束；另一次解析调用负责把结果整理成output_schema定义的结构。当主模型输出不稳定、或主模型格式遵循能力偏弱时，就选这条路。

agent = Agent( model=OpenAIResponses(id="gpt-5.2"), output_schema=NationalParkAdventure, parser_model=OpenAIResponses(id="gpt-5.2"), ) run: RunOutput = agent.run(national_parks[random.randint(0, len(national_parks) - 1)])

示例中的NationalParkAdventure共 11 个字段，还用Field(ge=1, le=5)与Field(ge=1, le=14)约束了难度评级和建议天数两个数值字段。实测 46s PASS。

agno 双模型精修输出：output_model

output_model: Optional[Model]（agent.py L309）拿到与主模型相同的对话，自己生成一份回复并直接替换主模型输出。典型用法是便宜模型负责推理与工具调用，强模型负责产出最终精修文案，再用output_model_prompt指定改写风格。注意边界：要的是结构化 JSON 时请改用parser_model，别选output_model。

agent = Agent( model=OpenAIResponses(id="gpt-5-mini"), output_model=OpenAIResponses(id="gpt-5.2"), output_model_prompt="Rewrite the recipe with vivid descriptions, pro tips, and elegant formatting.", ) run: RunOutput = agent.run("Give me a recipe for pad thai.") pprint(run.content)

实测 49s PASS；相对output_schema多出的秒数，正来自"主模型 + 输出模型"两次调用的开销。

三条路径选型速览

运行侧：agno Agent 流式响应的三种消费方式

逐 token 输出：stream=True

streaming.py是 agno Agent 流式响应的最小示例，核心只有一个参数：

agent = Agent(model=OpenAIResponses(id="gpt-5.2"), markdown=True) agent.print_response("Explain the difference between concurrency and parallelism.", stream=True)

print_response内部完成富文本渲染与逐 token 打印，适合交互式演示。实测 9s PASS。

捕获为变量：run() 拿回完整 RunOutput

需要程序化处理结果时，把print_response换成run即可拿到完整RunOutput：

run_response: RunOutput = agent.run("What is the stock price of NVDA") pprint(run_response)

该示例的 agent 还配了YFinanceTools与markdown=True；流式变体run(..., stream=True)返回Iterator[RunOutputEvent]，可自行迭代消费每个事件。实测 12s PASS。

自动落盘：save_response_to_file

字段声明为save_response_to_file: Optional[str]（agent.py L320），默认None不落盘；配置后每次运行结束都会把响应写入指定文件。

agent = Agent( model=OpenAIResponses(id="gpt-5.2"), save_response_to_file="tmp/agent_output.md", markdown=True, ) os.makedirs("tmp", exist_ok=True) agent.print_response("Write a brief guide on Python virtual environments.", stream=True) print(f"\nResponse saved to: {agent.save_response_to_file}")

易踩坑点：框架不会替你创建父目录，示例里显式os.makedirs("tmp", exist_ok=True)就是为此。实测 10s PASS。

参数速查：源码里的 I/O 字段一表看完

耗时数据的边界与延伸阅读

• 上表耗时均为 2026-02-13 在.venvs/demo/bin/python+ pgvector 环境下的单次实测，随模型版本与网络状态浮动，只宜作链路复杂度的相对参考，不构成性能承诺；
• 测试日志覆盖的是 9 个示例，目录里还有未纳入日志的followup_suggestions.py与followup_suggestions_streaming.py：前者用followups=True开启追问建议，num_followups默认 3（源码校验必须 ≥1，见 agent.py L648-L650），主回复之后会追加一次模型调用生成建议，可作为延伸阅读；
• 一句话收束：输入侧靠形态、字典、契约三层递进喂好问题，输出侧按成本与可控性在三条路径中选型，运行侧用流式、变量、落盘三种方式消费结果——这套 agno Agent 输入输出机制到这里就闭环了。

【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno