Gemini Agent 是什么？Google AI Agent 如何调用工具、API 和函数

最后更新于 2026 年 8 月 18 日。本篇技术结论核实自 Google 官方文档：Managed Agents（Gemini Agent）、Function calling 与 Using Tools with Gemini API。

症状：产品文档里同时出现 Gemini、Agent、Tools、Function calling，团队不知道该接 Interactions API、自管循环，还是托管 Agent。
最快解法：先分清「模型会生成调用意图」和「谁真正执行副作用」；内置工具走 Google 沙箱，自定义函数必须由你的应用执行并回传 function_result。

谁该看这篇：

• 要把 Google AI Agent 接到订单、工单、知识库或内部 API 的后端工程师；
• 正在比较自研 Agent Loop 与 Gemini Managed Agents 的架构负责人；
• 已经能聊天，但不能安全写库、发邮件或改配置的平台团队。

Gemini Agent 到底指哪一层

日常沟通里的「Gemini Agent」至少有三层，混在一起就会把采购、权限和排障全部做反。

第一层是会推理的 Gemini 模型。它可以根据你声明的函数 Schema，在回复中产出结构化的 function_call，而不是只能输出自然语言。这一层解决的是「模型知不知道该调什么」，并不自动拥有你的数据库密码，也不会替你发真实 HTTP 请求。

第二层是Gemini API 的工具能力。官方把 Tools 定义为可在一次对话或 Live 会话中被模型请求的能力：既可以是 Google Search、Code Execution、URL Context 这类托管工具，也可以是你自己声明的 Function Calling。详见 Gemini API Tools 文档。

第三层才是产品意义上的 Gemini Agent / Managed Agents。你可以把系统指令、默认工具、远程 MCP、自定义函数、文件与 AGENTS.md/SKILL.md 固化成一个可按 ID 调用的 Agent；调用时用 Interactions API，而不是每次手写完整循环。官方说明默认工具包含 code_execution、google_search 和 url_context，也可以在单次 interaction 覆盖。见 Building Managed Agents。

对工程决策更有用的判断是：如果你只需要一次结构化取数，Function calling 就够了；如果你需要沙箱、搜索、代码执行、远程 MCP 和可复用的 Agent 配置，再上 Managed Agents。不要因为名字里有 Agent，就把所有业务写进提示词。

工具、API 与函数如何分工

标题里的三个词对应三条不同的执行路径，不能互相替代。

• 工具（Tools）：给模型看的能力清单。内置工具由 Google 执行；自定义工具只是一份声明，执行权仍在你这边。
• API：你的业务接口、第三方 HTTP、数据库查询。模型永远看不到密钥，它只生成参数；由你的服务用正式鉴权去打真实 API。
• 函数（Functions）：本地代码、SDK 方法、队列生产者。声明用 JSON Schema，运行时用 name + arguments + 唯一 id 对齐结果。

官方把 Function calling 的三类用途写得很清楚：采取行动（预约、开票、发信）、增强知识（查库、查文档）、扩展能力（计算器、出图）。这和「让模型直接生成最终 JSON 给前端渲染」不是一回事。需要中间步骤连接外部系统时用 Function calling；只要最终回答符合某个 Schema，用 Structured Outputs。见 Function calling 指南。

如果你已经在别的模型上踩过工具循环，可以把同一套编排纪律迁过来。例如我们写过 Kimi K3 Tool Calls 循环怎么办？2026 止损教程：消息链、流式参数和幂等保护，在 Gemini 这边同样成立，只是字段名换成 function_call / function_result 与 previous_interaction_id。

一次完整的函数调用循环

一次可靠的调用，不是「模型吐了个函数名就算成功」。官方流程可以压成五步，缺任何一步都会在生产里表现为重复下单或胡编参数。

1. 声明：把 name、description 和 JSON Schema 参数交给模型。描述要写清何时该用、何时不该用，而不是只写「获取数据」。
2. 请求：用户输入与 tools 一起发给 interactions.create 或 generateContent。
3. 模型决策：可能直接回答，也可能返回 function_call，带上 id 和 arguments。
4. 你来执行：校验类型、鉴权、超时、幂等键，再打真实 API 或本地函数。模型不会替你执行自定义代码。
5. 回传结果：用同一个 id 提交 function_result，必要时带上 previous_interaction_id，让模型生成用户可读回复，或继续下一轮工具。

最小声明长这样——真正上线时把 order_id 等业务字段写进 required，并禁止模型发明不存在的枚举值：

{
  "type": "function",
  "name": "get_order_status",
  "description": "按订单号查询履约状态，禁止用于创建或取消订单。",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {"type": "string", "description": "业务订单号，例如 OD-20260818-001"}
    },
    "required": ["order_id"]
  }
}

执行层不要把模型参数直接拼进 SQL 或 Shell。先做 Schema 校验，再映射到内部 DTO，最后用服务账号调用 API。返回给模型的内容只保留它下一轮推理需要的字段，不要把完整用户档案或密钥回灌进上下文。

并行调用和组合调用是两件不同的事。一次 turn 里多个 function_call 可以同时查询库存和物流；组合调用则是先查地点再查天气，必须等上一跳结果回来。官方 Interactions 示例用天气和恒温器说明：先 get_weather_forecast，再决定 set_thermostat_temperature。你的编排器要按 id 等待，而不是看到函数名就重放整条链。

内置工具与自定义函数的执行边界

Google AI Agent 最容易写错的地方，是把「模型请求了工具」理解成「服务端已经做完」。官方 Tools 文档把两条路径拆开：

• 内置工具：搜索、代码执行、URL 上下文等由 Google 管理。沙箱里的步骤会自动产生匹配的 function_result。
• 自定义函数 / Computer Use：你的应用负责执行。模型只给出结构化 JSON，例如 {"name":"get_order_status","args":{"order_id":"123"}}，并带唯一 id。

Managed Agents 把这件事说得更硬：当自定义函数和沙箱工具混用时，API 用 step matching。内置工具在服务端跑完；尚未执行的自定义调用会让 interaction 进入 requires_action。客户端要过滤已经有 function_result 的 call_id，只执行 pending 的 function_call，再把结果送回。漏过滤就会对同一 id 执行两次，这在支付和建单场景里是事故而不是重试。

因此，生产编排至少要保存四类证据：原始 function_call、本地执行日志、回传的 function_result、以及 interaction 状态（完成 / requires_action / 失败）。只看聊天窗口里的「已调用工具」不够。

本地 Agent 连不上模型时，问题往往在网关、密钥和模型列表，而不是 Schema。排查顺序可以参考 Prime Agent Ollama 2026：连不上排查：先证明传输层通，再谈工具循环。

调用模式、MCP 与组合调用

模型什么时候必须调工具，由配置约束，而不是靠提示词碰运气。Interactions 文档用 tool_choice 描述模式：

• auto（默认）：模型自己决定回答还是调用；
• any：强制产生函数调用，适合「这一步必须落到系统」的工作流节点；
• none：禁止调用，适合纯解释或复盘；
• validated（预览）：强调 Schema 遵从。

把「查天气」设成 any 没问题；把「删除生产数据」设成 any 且没有人工审批，就是在用模型当定时炸弹。高副作用工具应默认 auto 或白名单，并在执行层再卡一道。

远程 MCP 让 Agent 接到外部工具服务器：配置里提供 name 和 url。这对 IDE、内部网关和多团队工具目录很方便，但鉴权、网络出口和工具可见范围必须由你定义。不要把未鉴权的 MCP 暴露到公网，再指望模型「自己小心」。

多工具混用时，Gemini 3 系列可以在同一次 interaction 里组合内置工具与自定义函数；previous_interaction_id 会把内置工具上下文带下去。对你意味着：日志必须按 interaction 而不是按单次 HTTP 请求归档，否则组合调用的第二跳会看起来像「模型无故又调了一次」。

流式场景还要冻结参数组装。官方支持把函数参数以增量 arguments 推过来，你必须聚合完整 JSON 再执行，禁止对半截 order_id 打生产 API。

上线前必须卡住的风控点

Function calling 能跑通 Demo，离能跑无人值守任务差的是控制面。建议按下面六项验收，全部通过再打开写操作。

1. 权限最小化：读订单和改订单分成两个函数；模型看不到的能力不要出现在 Schema 里。
2. 幂等：所有创建、扣款、发信带业务幂等键，用 function_call.id 或你自己的 request-id 去重。
3. 超时与取消：自定义函数必须有 deadline；超时返回明确错误对象，而不是空字符串，以免模型换参数重试。
4. 结果最小化：回传状态码、摘要、下一步建议，不要回传完整行级数据。
5. 轮次与费用预算：限制单任务工具次数、墙钟时间和 token；超限进入人工队列。
6. 可回放：保存声明版本、模型版本、arguments、结果哈希，才能判断是 Schema 漂移还是业务 bug。

若工具结果可能已经写入业务系统，禁止「再让模型试一次」。先查幂等表。若只是前端把同一次调用渲染了两遍，修日志聚合，不要改提示词。这些判断和 Kimi 侧的止损顺序一致，差别只在 Gemini 多了 requires_action 这一状态。

选型上可以记住三句话：只要结构化最终答案，用 Structured Outputs；只要连接你的 API，用 Function calling；要沙箱、搜索、MCP 和可复用配置，再用 Managed Agents。三套能力可以出现在同一条产品里，但执行责任必须写进架构图，而不是写进营销页。

把 Gemini Agent 的工具循环跑在会休眠的笔记本上，常见后果是 requires_action 回调丢失、日志被截断、MCP 长连接断开。临时云主机能拉起进程，却不容易长期保留完整 interaction 记录和固定的 macOS 工具链。需要持续复现函数调用、保存调试日志并远程接管时，租用 Kvmkit 的 Mac 环境通常比占用个人电脑更稳：机器可保持在线，Homebrew、Docker 与证书链也更好对齐。你可以先看 帮助中心 的远程条件，再对照 美国东部 Mac mini 租用方案。若必须接本地 USB 或专网设备，自购仍然更合适；但对 Gemini 工具循环的夜间回归和审计留存，稳定在线的远程 Mac 更容易留下可核对的证据。