实用笔记：我通过三种方式构建了相同的智能体：交互API、ADK，以及

本指南将展示如何从原始材料构建出可运行的系统：我用三种方式创建了相同的智能体——交互 API、ADK 以及反重力 SDK。重点在于可操作的步骤、明确的检查点，以及无需猜测意图即可直接放入代码库的代码。 在概览阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏的状态。 除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在系统从演示环境过渡到共享环境时出现意外费用。

设置与操作指南

在完成设置与逐步操作阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审计。 在耗时较高的步骤之后设置检查点。当操作人员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。

export GOOGLE_API_KEY="..."   # get this at aistudio.google.com
gcloud auth application-default login

方法1：交互API，由你编写工具与循环逻辑

在处理方法1的Interactions API阶段时，首先需明确接口规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改不会偏离原有设计。

同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。

每次调用都要记录工具名称、参数哈希值、延迟时间以及执行结果。没有这些记录，调试过程将会浪费大量时间。

def execute_sql(query: str) -> list[dict]:
    client = bigquery.Client()
    config = bigquery.QueryJobConfig(maximum_bytes_billed=20 * 10**9)
    rows = client.query_and_wait(query, job_config=config, max_results=50)
    return [{k: str(v) for k, v in dict(row).items()} for row in rows]

execute_sql_tool = {
    "type": "function",
    "name": "execute_sql",
    "description": (
        "Run a BigQuery Standard SQL SELECT query against "
        "`bigquery-public-data.hacker_news.full`, the public Hacker News "
        "dataset (stories and comments since 2006). Columns: id INT, "
        "type STRING (story/comment/job/poll), title STRING (stories only), "
        "text STRING (body, HTML-escaped), `by` STRING (username), score INT, "
        "parent INT, descendants INT, timestamp TIMESTAMP, url STRING, "
        "dead BOOL, deleted BOOL. Returns at most 50 rows."
    ),
    "parameters": {
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
    },
}

while True:
    calls = [s for s in interaction.steps if s.type == "function_call"]
    if not calls:
        break
    results = [{
        "type": "function_result",
        "name": step.name,
        "call_id": step.id,
        "result": [{"type": "text", "text": json.dumps(execute_sql(**step.arguments))}],
    } for step in calls]
    interaction = client.interactions.create(
        model=MODEL,
        input=results,
        system_instruction=INSTRUCTION,
        tools=[execute_sql_tool],
        previous_interaction_id=interaction.id,
    )

方法2：ADK，框架自带工具

在按照方法2的ADK流程进行开发时，首先需明确规范：所需的输入参数、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改始终符合预期。 相比冗长的脚本，更应采用小型且可测试的单元。当某个步骤出现故障时，故障点应指向单一责任模块，而非复杂的流程链。 需为每次调用记录工具名称、参数哈希值、延迟时间以及执行结果。若没有这些记录，调试过程将会浪费大量时间。 在按照方法2的ADK流程进行开发时，首先需明确规范：所需的输入参数、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改始终符合预期。 在功能结果旁还需记录执行时间以及代币或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。

import google.auth
from google.adk import Agent
from google.adk.integrations.bigquery import BigQueryCredentialsConfig, BigQueryToolset
from google.adk.integrations.bigquery.config import BigQueryToolConfig, WriteMode

credentials, _ = google.auth.default()
toolset = BigQueryToolset(
    credentials_config=BigQueryCredentialsConfig(credentials=credentials),
    bigquery_tool_config=BigQueryToolConfig(write_mode=WriteMode.BLOCKED),
)
root_agent = Agent(name="hn_opinion_agent", model=..., instruction=..., tools=[toolset])

方法3：反重力SDK，即吊带系统与MCP的结合

将方法3中的反重力SDK平台视为可测量的表面来使用效果最佳。在扩大应用范围之前，需记录一份成功的案例、一个失败案例以及回滚说明。 配置信息应置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。 所提供的工具应具有明确的架构定义和清晰的副作用标签。主机需要在自动批准之前知道哪些调用会改变系统状态。

from google.antigravity import Agent, LocalAgentConfig
from google.antigravity.types import McpStreamableHttpServer

bigquery_mcp = McpStreamableHttpServer(
    name="bigquery",
    type="http",
    url="https://bigquery.googleapis.com/mcp",
    headers={"Authorization": f"Bearer {token}",
             "x-goog-user-project": project},
    enabled_tools=["execute_sql_readonly", "get_table_info", ...],
)
config = LocalAgentConfig(system_instructions=..., mcp_servers=[bigquery_mcp])
async with Agent(config) as agent:
    response = await agent.chat(question)

对比分析

将比较阶段视为可测量的对象时，其效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。同时记录正常流程和恢复流程的文档。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续需要补充的内容。保持图结构的层次简单且类型明确，嵌套的数据块会掩盖哪个节点编写了哪个字段的信息，还会在中断后导致流程无法继续。

提供服务

将“服务提供阶段”视为可度量的对象来处理时，其效果最佳。在扩大范围之前，需记录一份理想的运行日志、一个故障案例以及回滚说明。 相比庞大的脚本，应优先使用小型且可测试的单元。当某一步骤出现故障时，故障应指向单一责任模块，而非复杂的流程链。 保持图结构的状态简洁且具有类型定义。嵌套的数据块会掩盖哪个节点修改了哪个字段的信息，还会在流程中断后导致无法继续执行。 将“服务提供阶段”视为可度量的对象来处理时，其效果最佳。在扩大范围之前，需记录一份理想的运行日志、一个故障案例以及回滚说明。 除了功能结果外，还需记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。

关于服务账户的说明

对于舞台上的A笔记，在修改代码之前需明确输入参数、该步骤的负责人以及退出标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个流程即可进行审计。 对于涉及资金支出或修改生产数据的节点，需设置人工审批环节。编译时的连接方式并不等同于业务流程的完整性。

应选择哪种方案

在“选择使用哪个版本”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和异常恢复路径。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的内容。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务功能的完整性。

操作检查清单

将“操作检查清单”阶段视为可衡量的工作面，能使其发挥最佳作用。在扩大范围之前，需记录一份标准操作流程、一个故障案例以及回滚说明。 应将此阶段视为输入参数与经过验证的输出结果之间的契约。为相关文档命名，明确成功标准，杜绝默许的不完整处理方式。

保持图状态扁平且具有类型约束。嵌套的二进制数据会隐藏是哪个节点修改了哪个字段，还会在中断后导致程序无法继续运行。

只要预算允许，就在持续集成过程中使用测试用例而非真实的付费 API 来执行关键路径的烟雾测试。

在功能结果旁记录处理时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外账单。

保持图状态扁平且具有类型约束。嵌套的二进制数据会隐藏是哪个节点修改了哪个字段，还会在中断后导致程序无法继续运行。

在升级技术栈之前，先冻结版本，为关键路径生成标准操作记录，并确认回滚步骤。共享环境需要设置速率限制、租户验证机制，以及明确的密钥轮换负责人。与其追求花哨的一次性演示，不如注重扎实的可靠性。

关于016bc4c24234的批量处理说明：不要将提供者密钥放入代码仓库，为每个会话设置令牌使用上限，并将转录内容存储在评估测试用例的旁边，以便后续更换模型时仍能保持可比性。

在处理强化安全性的第0阶段时，首先需写下相关规范：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改符合要求。将此阶段视为输入与验证后输出之间的契约，为相关文件命名、定义成功判定标准，并拒绝默许部分完成的情况。

强化安全性细节0/754：需统计该处理步骤的运行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非主观判断来决定是否保留该更改。

在将加固措施视为可测量的表面时，第0阶段的效果最佳。在扩大范围之前，先记录一份理想的运行日志、一个故障案例以及回滚说明。 同时记录正常流程和恢复流程。重试机制、人工审核环节以及错误处理都属于产品本身的功能，而非后续需要补充的内容。

加固细节0/773：针对此条说明，需测量处理时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。

对于加固措施的第1阶段，在修改代码之前需明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入参数与经过验证的输出结果之间的契约。为相关成果命名，定义成功检测标准，并拒绝默许的半完成状态。

强化细节 1/773：测量该笔记的运行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来决定是否保留该变更。