如何通过编程方式与 Agent Builder 创建的智能体进行对话-Python教程-PHP中文网

如何通过编程方式与 Agent Builder 创建的智能体进行对话

本文介绍如何使用 google cloud dialogflow cx sdk 调用由 vertex ai agent builder 构建的无代码智能体，实现 web 或移动端的程序化交互，重点提供可直接运行的 python 示例及关键配置说明。

本文介绍如何使用 google cloud dialogflow cx sdk 调用由 vertex ai agent builder 构建的无代码智能体，实现 web 或移动端的程序化交互，重点提供可直接运行的 python 示例及关键配置说明。

Google Cloud Vertex AI Agent Builder 是一个低代码/无代码平台，用于快速构建基于 Gemini 大模型的智能体（Agent），并支持 RAG（检索增强生成）等高级能力。虽然它在 UI 上独立呈现，但其底层实际托管为 Dialogflow CX agent，并可在 Dialogflow CX 控制台中查看和管理。这意味着——你无需额外 SDK 或私有 API，即可直接复用官方 google-cloud-dialogflow-cx 客户端库完成程序化调用。

以下是完整的端到端调用流程与注意事项：

通义灵眸

通义灵眸是一款AI文本写作工具，阿里通义推出的AI数字人生产平台。

下载

✅ 前置准备

已在 Agent Builder 控制台创建并部署了 Agent（Playbook 已发布）；
在 Google Cloud Console 中启用 Dialogflow CX API（注意：不是 Dialogflow ES）；
为服务账号配置 roles/dialogflow.sessions.user 权限（推荐最小权限原则）；
获取以下关键参数：
- PROJECT_ID：GCP 项目 ID；
- LOCATION_ID：Agent 所在区域（如 us-central1，必须与 Agent 实际部署位置一致）；
- AGENT_ID：Agent 的唯一 UUID（可在 Dialogflow CX 控制台 URL 或 Agent 列表详情页中找到，格式类似 abcd1234-5678-90ef-ghij-klmnopqrstuv）。

✅ 核心调用代码（Python）

import uuid
from google.cloud.dialogflowcx_v3beta1.services.sessions import SessionsClient
from google.cloud.dialogflowcx_v3beta1.types import session

# 替换为你的实际配置
PROJECT_ID = "your-gcp-project-id"
LOCATION_ID = "us-central1"  # ⚠️ 必须与 Agent 部署区域严格一致
AGENT_ID = "your-agent-uuid-here"
AGENT = f"projects/{PROJECT_ID}/locations/{LOCATION_ID}/agents/{AGENT_ID}"
LANGUAGE_CODE = "en-us"  # 支持多语言，如 "zh-cn"

# 构建会话路径（每次对话需唯一 session_id）
SESSION_ID = uuid.uuid4()
session_path = f"{AGENT}/sessions/{SESSION_ID}"

# 自动适配区域化 endpoint（非 global location 需显式指定）
client_options = None
if LOCATION_ID != "global":
    api_endpoint = f"{LOCATION_ID}-dialogflow.googleapis.com:443"
    client_options = {"api_endpoint": api_endpoint}

session_client = SessionsClient(client_options=client_options)

# 发送用户输入
text_input = session.TextInput(text="你好，请帮我查一下最新财报摘要")
query_input = session.QueryInput(text=text_input, language_code=LANGUAGE_CODE)
request = session.DetectIntentRequest(
    session=session_path,
    query_input=query_input
)

response = session_client.detect_intent(request=request)

# 解析响应（支持富媒体消息，此处仅提取纯文本）
query_text = response.query_result.text
response_texts = [
    " ".join(msg.text.text) for msg in response.query_result.response_messages if msg.text.text
]
print(f"User: {query_text}")
print(f"Agent: {' '.join(response_texts) or '(no text response)'}")

⚠️ 关键注意事项

版本选择：务必使用 dialogflowcx_v3beta1（而非 v3），因 Agent Builder 当前依赖该 beta 版本的会话接口；
区域一致性：LOCATION_ID 错误将导致 NOT_FOUND 或 PERMISSION_DENIED 错误，可在 Agent Builder 控制台右上角或 Dialogflow CX 控制台 URL 中确认；
会话生命周期：每个 session_id 对应一次独立会话（含上下文记忆）。若需长期上下文，建议在客户端维护 session ID 并复用（注意超时：默认 20 分钟无活动自动过期）；
响应结构：response.query_result.response_messages 可能包含 text、payload（JSON 结构化数据）、card 等多种消息类型，适用于 Web App 渲染富交互界面；
认证方式：本地开发推荐使用 gcloud auth application-default login；生产环境请使用服务账号密钥文件，并通过 GOOGLE_APPLICATION_CREDENTIALS 环境变量加载。