在 Gemini Enterprise Agent…

当需要在 GEAP 上使用有状态、服务端托管的 Gemini Interactions API 构建多轮对话、后台任务、流式响应、结构化输出或工具调用时使用。

适用场景

解决思路

1. 使用统一的 Google Gen AI SDK：Python 用 `google-genai >= 2.3.0`，JS/TS 用 `@google/genai >= 2.3.0`；`>= 2.0.0` 是 steps schema 生效的最低版本，但推荐 `>= 2.3.0`。在解释客户端初始化或编写 import 代码时，必须明确警告用户：`google-cloud-aiplatform`、`@google-cloud/vertexai`、`google-generativeai` 等旧版 SDK 严格不支持 Interactions。
2. 只使用最新模型：`gemini-3.5-flash`（快速、均衡、多模态，推荐默认）、`gemini-3.1-pro-preview`（复杂推理、编码、研究）、`gemini-3.1-flash-lite`（低成本、高频轻量任务）；参考最新模型版本文档检查更新。在任何交互响应中必须警告用户：`gemini-3-flash-preview`、`gemini-2.5-*`、`gemini-2.0-*`、`gemini-1.5-*` 等旧模型已弃用且不支持 Interactions API。
3. 在 GEAP 上必须使用 `agent="<AGENT_ID>"` 参数指向已配置的 agent 或 endpoint，不能使用 `model="..."` 直接调用基础模型（GEAP 尚不支持）；按 Agent Platform 文档配置 agent 并传入其 ID。
4. 注意 `tools`、`system_instruction`、`generation_config` 等参数是 turn-scoped 的，必须在每次 interaction 请求中都传入。
5. 认证：运行 `gcloud auth application-default login` 登录 ADC，并用 `gcloud services enable aiplatform.googleapis.com` 启用 API。
6. 客户端初始化方式 A（推荐，环境变量）：设置 `export GOOGLE_GENAI_USE_ENTERPRISE=true`、`export GOOGLE_CLOUD_PROJECT="your-project-id"`、`export GOOGLE_CLOUD_LOCATION="global"`；Python 用 `client = genai.Client()`，TS/JS 用 `const ai = new GoogleGenAI();`，SDK 会自动读取环境变量。
7. 客户端初始化方式 B（显式内联参数）：Python 用 `google.auth.default()` 获取 project_id 后 `genai.Client(enterprise=True, project=project_id, location="global")`；TS/JS 用 `new GoogleGenAI({ enterprise: { project: "your-project-id", location: "global" } })`。
8. 单轮快速开始：调用 `client.interactions.create(agent="your-agent-id", input="...")`，从 `steps` 列表中读取输出，用 `interaction.output_text` 便捷访问器获取尾部 `model_output` 步骤的合并文本。
9. 有状态多轮对话：Interactions 默认有状态（`store=True`），第一轮传入 `store=True` 并保存返回的 `turn1.id`，后续轮次用 `previous_interaction_id=turn1.id`（TS/JS 为 `previousInteractionId`）引用已存储的对话状态；传 `store=False` 会禁用服务端保留，同时禁用 `previous_interaction_id` 和 background。
10. 实时流式输出：传入 `stream=True` 返回可迭代的 chunk 生成器；事件序列为 `interaction.created -> (step.start -> step.delta(s) -> step.stop)+ -> interaction.completed`；遍历事件，当 `event.event_type == "step.delta"` 且 `event.delta.type == "text"` 时打印 `event.delta.text`，在 `interaction.completed` 时换行。
11. 结构化输出：Python 用 Pydantic `BaseModel` 定义 schema（如 `Book`，含 `title`、`author`、`year_published` 字段及 `Field(description=...)`），通过 `response_format=Book` 传入；TS/JS 用 `Type.OBJECT` 等定义 schema 对象并通过 `responseFormat` 传入；`interaction.output_text` 将是符合 schema 的合法 JSON。
12. 函数调用（Agent 工具使用）：定义本地函数（如 `get_stock_price(ticker)`），第一轮通过 `tools=[get_stock_price]` 传入；在扁平 steps schema 中，工具请求是顶层 `type == "function_call"` 的 step，含扁平的 `name` 和 `arguments` 字段（没有嵌套的 `tool_calls`）；遍历 `interaction.steps` 找到匹配的 function_call step，用 `step.arguments.get("ticker")` 取参数并执行本地函数。
13. 提交函数结果：第二轮调用 `client.interactions.create`，`input` 传 `[{"type": "function_result", "name": step.name, "call_id": step.id, "result": [{"type": "text", "text": json.dumps(price)}]}]`，同时再次传入 `tools=[get_stock_price]`（turn-scoped）和 `previous_interaction_id=interaction.id`，然后读取 `final_turn.output_text`。
14. 通过 REST 访问：端点 `POST https://aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{LOCATION}/interactions`，LOCATION 用 `global`；设置 `AGENT_ID="your-agent-id"` 和 `ACCESS_TOKEN=$(gcloud auth print-access-token)`。
15. REST 单轮请求：用 `curl -X POST` 携带 `Authorization: Bearer ${ACCESS_TOKEN}` 和 `Content-Type: application/json`，body 为 `{"agent": "${AGENT_ID}", "input": [{"type": "user_input", "content": [{"type": "text", "text": "..."}]}]}`；同步 POST 返回含 `id`、`status`、`steps`、`usage`、`created`、`updated`、`environment_id`、`object` 的 JSON。
16. REST 多轮有状态请求：在 body 中加入 `"store": true` 和 `"previous_interaction_id": "YOUR_PREVIOUS_INTERACTION_ID"`，input 同样用 `user_input` 结构。
17. REST 流式请求：在 body 中传 `"stream": true`，服务端返回 `Transfer-Encoding: chunked` 和 `Content-Type: text/event-stream`（SSE），每个事件以 `data: ` 开头包含带 `event_type` 和 step 内容的 JSON；curl 会自动保持连接并实时打印数据块，无需轮询。
18. 读取响应时检查当前 step 的 `type` 而非假设最后一步是文本：`user_input`（用户输入，含 `content` 数组，REST 用 `"type": "user_input"` 而非 `"role": "user"`）、`model_output`（最终模型生成，含 `content` 数组，REST 用 `"type": "model_output"` 而非 `"role": "model"`）、`thought`（模型推理/思维链，含 `signature` 和可选 `summary`）、`function_call`（工具调用请求，扁平 `id`/`name`/`arguments`，无嵌套 `tool_calls`）、`function_result`（工具结果，含 `call_id`/`name`/`result`），以及 `google_search_call`/`google_search_result`、`code_execution_call`/`code_execution_result`、`url_context_call`/`url_context_result`、`mcp_server_tool_call`/`mcp_server_tool_result`、`file_search_call`/`file_search_result` 等内置和远程工具步骤。
19. content 数组内的内容类型：`text`（`text` 字段）、`image`/`audio`/`document`/`video`（含 `data`、`mime_type` 或 `uri`）。
20. 优先使用 `output_text` 便捷访问器获取尾部 `model_output` 步骤的合并文本，而不是手动遍历 `steps[-1].content[0].text`（当最后一步是工具调用或 thought 时会出错）。
21. 流式事件类型：`interaction.created`（交互已创建，含元数据）、`step.start`（新步骤开始，含步骤 `type` 和初始元数据）、`step.delta`（当前步骤的增量数据，含类型化 `delta` 对象，如 `delta.type == "text"` 时含 `delta.text`）、`step.stop`（步骤完成，含 `index`）、`interaction.completed`（交互完成，含最终 `usage`）。
22. 存储与保留：Interactions 默认存储（`store=True`），启用 `previous_interaction_id` 和后台执行等有状态特性；传 `store=False` 禁用服务端保留，从而也禁用 `previous_interaction_id` 和 `background`，此时必须在每轮 `input` 中传入完整对话历史。

适用边界 · 注意事项

• 不在 Gemini Enterprise Agent Platform 上、而是直接使用 ai.google.dev 的 Gemini API 时（该文档用 `model=...`，与 GEAP 的 `agent=...` 用法不同）。
• 尚未在 GEAP 上配置好 agent 或 endpoint 时（GEAP 尚不支持直接/基础模型调用）。
• 使用旧版 SDK（`google-cloud-aiplatform`、`@google-cloud/vertexai`、`google-generativeai`）或旧模型（`gemini-2.5-*`、`gemini-2.0-*`、`gemini-1.5-*`）时，Interactions API 不受支持。