企业官网建设流程全解析

AI Agent输出不听话？Google Antigravity SDK结构化输出（Pydantic Schema）强制类型响应完整教程

【免费下载链接】antigravity-sdk-pythonA Python library for building AI agents that leverage the full power of Google Antigravity.项目地址: https://gitcode.com/gh_mirrors/an/antigravity-sdk-python

做 AI Agent 开发的朋友都踩过这个坑：模型返回的是一大段自然语言，你要用正则硬抠出日期、人名、数字，稍微换个措辞解析就崩。Google Antigravity SDK的结构化输出功能可以彻底解决这个问题——通过 Pydantic Schema 定义字段与类型，SDK 会让模型强制输出严格匹配的 JSON，拿到手就是类型安全的字典，直接喂给数据库、API 或下游工作流。本文带你 3 步掌握这个能力。

一、为什么 AI Agent 的文本输出"不听话"？

默认情况下，Agent 的回复是一段自由文本。如果你的下游程序需要从中提取结构化数据，通常会这样"裸奔"：

• 用正则表达式去匹配"截止日期[:：]?\s*(\S+)"—— 换个写法就失效；
• 让模型"请以 JSON 格式输出" —— 模型可能夹带解释性文字、多余逗号，json.loads一炸整个流程中断。

结构化输出的核心思路：不要"请求"模型输出 JSON，而是约束它——在会话配置中声明response_schema，模型在推理时就会感知到这个 Schema，最终输出被"钉死"在字段名、类型、必填项上。🎯

二、三步上手：用 Pydantic 定义 Schema 强制类型响应

第 1 步：安装 SDK

pip install google-antigravity export GEMINI_API_KEY="your_api_key_here"

SDK 本身依赖pydantic>=2.0，安装后即可使用（见 pyproject.toml 的依赖声明）。

第 2 步：用 Pydantic 模型描述"我要什么数据"

import pydantic class ActionItem(pydantic.BaseModel): assignee: str # 负责人 task: str # 任务 deadline: str # 截止日期 class MeetingSummary(pydantic.BaseModel): action_items: list[ActionItem]

只写类型，不写解析逻辑。str、int、float、list、dict、嵌套模型都可以，Pydantic 负责描述"形状"，SDK 负责传达给模型。

第 3 步：配置 Agent 并读取强类型结果

from google.antigravity import Agent, LocalAgentConfig config = LocalAgentConfig(response_schema=MeetingSummary) async with Agent(config) as agent: response = await agent.chat("从这段会议记录中提取行动项：...") data = await response.structured_output()

response.structured_output()返回已解析的字典（结构与 Schema 完全一致），解析失败时返回None——记得加个判空。该方法的实现在 types.py，它从对话的最后一步（FINISH）中提取结构化负载，底层由 conversation.py 的get_last_structured_output支撑。

⚡ 关键记忆点：配置用response_schema，取结果用structured_output()，一"写"一"读"。

三、完整实战：从非结构化会议记录提取行动项

仓库提供了一个可直接运行的完整示例：structured_output.py

它的玩法很贴近真实业务：

1. 注册一个自定义工具fetch_unstructured_meeting_notes，返回一段杂乱的自然语言会议记录（"Alice 说周一前更新测试、Bob 说明天跑 E2E 基准…"）；
2. Agent 配置时同时声明tools=[...]和response_schema=MeetingSummary；
3. Agent 调用工具拿到原始文本后，自动蒸馏成强类型的MeetingSummary对象；
4. 程序遍历data["action_items"]，每个行动项严格带有assignee/task/deadline三个字段，直接入库即可。

python structured_output.py

配套的讲解文档见 structured_output.md，快速上手索引在 examples/getting_started/README.md。

四、response_schema 支持哪些写法？

response_schema的定义位于 connection.py，SDK 的校验逻辑（connection.py#L121-L138）明确支持三种格式：

传其他类型（比如一个整数）会在配置阶段就抛出ValueError，属于快速失败，不会出现"运行到一半才发现格式不对"的尴尬。

五、避坑指南：新手最常踩的 3 个坑 🕳️

1. 忘记判空。structured_output()在解析失败或模型未产出结构化负载时返回None，直接data["action_items"]会抛TypeError。示例代码中的处理值得抄作业：

data = await response.structured_output() if not data: print("Fallback 到纯文本:", await response.text())

2. Schema 设计得太"贪心"。字段越多、嵌套越深，模型满足 Schema 的难度越高。建议：必填字段用具体类型（str、float），允许缺省的字段标| None = None，列表元素尽量扁平。

3. 把它当万能文本提取器。结构化输出最适合程序化消费的场景——写数据库、订日历、喂微服务、填充工单。如果只是给人看的回答，纯文本反而更自然。判断标准一句话：下游是代码还是人？

六、总结

一句话收尾：把"请输出 JSON"的口头请求，升级成 Schema 层面的强制约束——这就是 Google Antigravity SDK 结构化输出给你的确定性。去跑一遍 structured_output.py，你会发现下游解析代码几乎可以少写一半。

【免费下载链接】antigravity-sdk-pythonA Python library for building AI agents that leverage the full power of Google Antigravity.项目地址: https://gitcode.com/gh_mirrors/an/antigravity-sdk-python