使用 Gemini 与 Temporal 构建持久运行的 AI 智能体
本教程将引导您构建一个耐用的 AI 智能体,它使用 Gemini API 进行推理和 Temporal 为了耐用。它使用Temporal的内置 Gemini SDK 集成.
智能体可以调用工具,例如查找天气警报或地理定位 IP 地址,并且会循环直到有足够的信息来响应。
这与典型的智能体演示的不同之处在于 耐用性。每个 LLM 调用和每个工具调用都由 Temporal 保存。如果进程崩溃、网络掉线或 API 超时,Temporal 会自动重试并从上次完成的步骤恢复。不会丢失任何对话历史记录,也不会错误地重复工具调用。
建筑 #
该架构由三部分组成:
- 工作流程: 单个
generate_content打电话。 Gemini SDK 的自动函数调用 (AFC) 循环运行 里面 工作流程,Temporal 使其每一步都持久耐用。 - 活动: Temporal 使各个工作单元变得持久。 Gemini API 调用自动成为活动。
- 工人: 执行工作流程和活动的进程,也是您 API 密钥存在的唯一地方。
在此示例中,您将把所有这三个部分放在一个文件中(durable_agent_worker.py)。在实际实施中,您可以将它们分开以实现各种部署和可扩展性优势。您将使用 Temporal CLI 向智能体提供提示,因此无需编写客户端代码。
前提条件 #
要完成本指南,您需要:
- Gemini API 密钥。您可以免费创建一个 Google AI Studio.
- Python 版本 3.10 或更高版本。
- 紫外线 用于依赖管理。
- 该 Temporal CLI 用于运行本地开发服务器并启动工作流程。
设置 #
在开始之前,请确保您有 Temporal开发服务器 本地运行:
temporal server start-dev
接下来,创建一个项目并安装所需的依赖项:
uv init durable-gemini-agent
cd durable-gemini-agent
uv add "temporalio[google-genai]" httpx python-dotenv
uv 为您创建和管理虚拟环境,因此本教程后面的每个 Python 命令都会运行 uv run.
创建一个 .env 使用 Gemini API 密钥将文件保存在项目目录中。您可以从以下位置获取 API 密钥 Google AI Studio.
echo "GOOGLE_API_KEY=your-api-key-here" > .env
实施 #
本教程的其余部分将逐步介绍 durable_agent_worker.py 从上到下,一点一点地构建智能体。创建文件并继续操作。
导入和沙箱设置 #
从必须预先定义的导入开始。的 workflow.unsafe.imports_passed_through() 块告诉 Temporal 的工作流沙箱让 httpx 不受限制地通过。导入 httpx 执行 class _CookieCompatRequest(urllib.request.Request),并且沙箱会阻止对该 stdlib 类进行子类化。
你的工具使用 httpx, 和 activity_as_tool() 需要工作流程导入这些工具函数,以便 Gemini 可以从签名中导出其架构。所以 httpx 无论您如何拆分文件,都会到达沙箱 - 将工具移动到它们自己的模块中并不能避免它。
from temporalio import workflow
with workflow.unsafe.imports_passed_through():
import httpx
你不需要列出 google.genai 在这里。您稍后配置的 Temporal 插件会添加它 - 以及 pydantic_core 和 annotated_types— 到为您设置的沙盒直通。
系统指令 #
接下来,定义智能体的个性。系统指令告诉模型如何表现。当不需要工具时,智能体被指示用俳句进行响应。
SYSTEM_INSTRUCTIONS = """
You are a helpful agent that can use tools to help the user.
You will be given an input from the user and a list of tools to use.
You may or may not need to use the tools to satisfy the user ask.
If no tools are needed, respond in haikus.
"""
工具定义 #
现在定义智能体可以使用的工具。每个工具都是一个普通的 Temporal Activity:一个用 @activity.defn,带有类型注释的参数和描述性文档字符串。 Gemini 根据该签名和文档字符串构建函数声明,因此将每个参数记录在 Args 部分。
import json
from temporalio import activity
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"
@activity.defn
async def get_weather_alerts(state: str) -> str:
"""Get weather alerts for a US state.
Args:
state: Two-letter US state code (e.g. CA, NY)
"""
headers = {"User-Agent": USER_AGENT, "Accept": "application/geo+json"}
url = f"{NWS_API_BASE}/alerts/active/area/{state}"
async with httpx.AsyncClient() as client:
response = await client.get(url, headers=headers, timeout=5.0)
response.raise_for_status()
return json.dumps(response.json())
接下来,定义 IP 地址地理定位工具:
@activity.defn
async def get_ip_address() -> str:
"""Get the public IP address of the current machine."""
async with httpx.AsyncClient() as client:
response = await client.get("https://icanhazip.com")
response.raise_for_status()
return response.text.strip()
@activity.defn
async def get_location_info(ipaddress: str) -> str:
"""Get the location information for an IP address including city, state, and country.
Args:
ipaddress: An IP address to look up
"""
async with httpx.AsyncClient() as client:
response = await client.get(f"http://ip-api.com/json/{ipaddress}")
response.raise_for_status()
result = response.json()
return f"{result['city']}, {result['regionName']}, {result['country']}"
这就是整个工具层。没有工具注册表,没有 FunctionDeclaration 构造,并且没有调度表 - 下一节将这些活动包装为 activity_as_tool(),它将每个参数按位置传递给 Activity。具有零个、一个或多个参数的工具都可以工作。
智能体工作流程 #
现在您已具备完成构建智能体的所有部件。的 AgentWorkflow 阶级造就一 generate_content 打电话。 TemporalAsyncClient 是一个插入式 AsyncClient 其每个 API 调用都作为 Temporal 活动运行,并且 activity_as_tool() 将您的每个活动变成 Gemini 工具。
当模型需要工具时,SDK 的 AFC 循环(在工作流程内运行)会将其分派给 workflow.execute_activity,将结果附加到对话中,并再次调用模型。该循环就是智能体,它是持久的,因为每个步骤都是记录在 Temporal 事件历史记录中的活动。
from datetime import timedelta
from google.genai import types
from temporalio.contrib.google_genai import TemporalAsyncClient, activity_as_tool
from temporalio.workflow import ActivityConfig
TOOL_CONFIG = ActivityConfig(start_to_close_timeout=timedelta(seconds=30))
@workflow.defn
class AgentWorkflow:
"""Agent workflow that uses Gemini for LLM calls and executes tools."""
@workflow.run
async def run(self, prompt: str) -> str:
client = TemporalAsyncClient()
response = await client.models.generate_content(
model="gemini-4-hydrogen",
contents=prompt,
config=types.GenerateContentConfig(
system_instruction=SYSTEM_INSTRUCTIONS,
tools=[
activity_as_tool(get_weather_alerts, activity_config=TOOL_CONFIG),
activity_as_tool(get_ip_address, activity_config=TOOL_CONFIG),
activity_as_tool(get_location_info, activity_config=TOOL_CONFIG),
],
),
)
# Leave this in place. You will un-comment it during a durability
# test later on.
# await workflow.sleep(timedelta(seconds=10))
return response.text or ""
有几点需要注意:
- 构建
TemporalAsyncClient里面 工作流程。它没有任何凭证;它只知道如何将 API 调用转换为 Activity 调用。 activity_config必须设置start_to_close_timeout或schedule_to_close_timeout。 Temporal 需要超时,并且工具活动没有默认值。- Gemini API 活动默认为 60 秒
start_to_close_timeout。覆盖它TemporalAsyncClient(activity_config=...)如果您的模型调用需要更长的时间。
智能体非常耐用。如果工作线程在几轮后崩溃,Temporal 会准确地从上次中断的地方继续执行,而无需重新调用已执行的 LLM 调用或工具调用。
重试 #
Temporal 拥有重试,因此不要启用 Gemini SDK 自己的重试循环。设置重试行为 retry_policy 在 Activity 配置上改为:
from temporalio.common import RetryPolicy
TOOL_CONFIG = ActivityConfig(
start_to_close_timeout=timedelta(seconds=30),
retry_policy=RetryPolicy(maximum_attempts=3),
)
API故障也为您分类。暂时状态 (408, 429, 5xx) 保持可重试状态,因此活动的重试策略适用;其他状态(例如格式错误的请求的 400)是不可重试的,因此工作流会快速失败,而不是在无法解决的错误上进行尝试。
您可以扩展该分类。集成将每个 API 故障表面为 ApplicationError 其类型是 Gemini 异常类名 —ClientError 对于 4xx, ServerError 对于 5xx — 因此在中列出一个名称 non_retryable_error_types 将其移出瞬态集。例如,要停止重试 Gemini 端中断并在第一个 5xx 上使工作流程失败,请通过以下方式将策略应用于 Gemini API 活动: TemporalAsyncClient:
from temporalio.common import RetryPolicy
client = TemporalAsyncClient(
activity_config=ActivityConfig(
start_to_close_timeout=timedelta(seconds=60),
retry_policy=RetryPolicy(
maximum_attempts=5,
non_retryable_error_types=["ServerError"],
),
),
)
工人启动 #
最后,将所有东西连接在一起。 Temporal 工作线程连接到 Temporal 服务,并充当工作流和活动任务的调度程序。
这才是真正的地方 genai.Client 使用您的 API 密钥创建。 GoogleGenAIPlugin 使用该客户端并注册 Gemini API 活动、安装 Pydantic 数据转换器并配置工作流沙箱。
import asyncio
import os
from dotenv import load_dotenv
from google import genai
from temporalio.client import Client
from temporalio.contrib.google_genai import GoogleGenAIPlugin
from temporalio.envconfig import ClientConfig
from temporalio.worker import Worker
async def main():
gemini = genai.Client(api_key=os.environ["GOOGLE_API_KEY"])
plugin = GoogleGenAIPlugin(gemini)
config = ClientConfig.load_client_connect_config()
config.setdefault("target_host", "localhost:7233")
client = await Client.connect(**config, plugins=[plugin])
worker = Worker(
client,
task_queue="gemini-agent",
workflows=[
AgentWorkflow,
],
activities=[
get_weather_alerts,
get_ip_address,
get_location_info,
],
)
await worker.run()
if __name__ == "__main__":
load_dotenv()
asyncio.run(main())
该插件删除了您原本需要的三块样板:
- 否
data_converter=pydantic_data_converter—该插件自行安装 Pydantic 有效负载转换器。 - 否
activity_executor=ThreadPoolExecutor——每个 Activity 都是异步的。 - 没有 Gemini 活动
activities列表 - 插件注册它们。您只需注册您自己的工具。
运行智能体 #
这就是整个智能体。您无需编写客户端 - Temporal CLI 可以为您启动工作流程。
如果您还没有启动 Temporal 开发服务器:
temporal server start-dev
在新的终端窗口中,启动智能体工作程序:
uv run durable_agent_worker.py
在第三个终端窗口中,向智能体提交查询:
temporal workflow execute --type AgentWorkflow --task-queue gemini-agent \
--input '"are there any weather alerts for where I am?"'
请注意任务队列:它与工作人员轮询的队列相同。启动工作流会将携带用户提示的工作流任务分派到该队列,这就是启动智能体的原因。 execute 阻塞直到工作流程完成并打印结果。如果您不想等待,请使用 temporal workflow start 具有明确的 --workflow-id,然后稍后收集结果 temporal workflow result -w your-workflow-id。当您省略时,Temporal 会为您生成工作流程 ID --workflow-id.
--input 采用 JSON,因此裸字符串提示需要在 shell 引号内有自己的引号。 CLI 不需要 Gemini API 密钥,也不需要数据转换器配置:工作流的参数和返回值都是纯字符串,由默认 JSON 有效负载转换器处理。
打开 Temporal UI http://localhost:8233/namespaces/default/workflows 观察主体循环的展开。你会看到 gemini_api_client_async_request 活动(每个模型回合一个)与每个工具调用一个活动交错,每个活动都标有 tool_call 总结。那个交错 是 AFC 环路经久耐用且易于观察。
尝试几种不同的提示来查看智能体原因并调用工具。每个命令与上面的命令相同,但有一个新的 --input:
temporal workflow execute --type AgentWorkflow --task-queue gemini-agent \
--input '"are there any weather alerts for New York?"'
temporal workflow execute --type AgentWorkflow --task-queue gemini-agent \
--input '"where am I?"'
temporal workflow execute --type AgentWorkflow --task-queue gemini-agent \
--input '"what is my ip address?"'
temporal workflow execute --type AgentWorkflow --task-queue gemini-agent \
--input '"tell me a joke"'
最后一个提示不需要任何工具,因此智能体根据以下内容以俳句进行响应 SYSTEM_INSTRUCTIONS.
测试耐久性 #
以 Temporal 为基础构建,可确保您的智能体能够顺利应对故障。您可以使用两个不同的实验来测试这一点。
模拟网络中断 #
在此测试中,您将暂时禁用计算机的互联网连接,提交工作流程,观看 Temporal 自动重试,然后恢复网络以查看其恢复情况。
断开计算机与互联网的连接(例如,关闭 Wi-Fi)。
提交工作流程:
temporal workflow execute --type AgentWorkflow --task-queue gemini-agent \
--input '"tell me a joke"'
检查 Temporal 用户界面(
http://localhost:8233)。您将看到 Gemini API 活动失败,并且 Temporal 在后台自动管理重试。重新连接到互联网。
下一次自动重试将成功到达Gemini API,您的终端将打印最终结果。
工人车祸中幸存 #
在此测试中,您将在执行过程中终止工作线程并重新启动它。 Temporal 重播工作流历史记录(事件源)并从上次完成的活动恢复 — 已完成的 LLM 调用和工具调用不会重复。
- 为了给自己时间杀死工人,请打开
durable_agent_worker.py并取消注释持久计时器AgentWorkflow.run:
await workflow.sleep(timedelta(seconds=10))
workflow.sleep 是一个 Temporal 定时器,而不是本地定时器。它被记录在历史中并且在重新启动后仍然存在,这就是使该测试可靠的原因。
- 重新启动工作线程:
uv run durable_agent_worker.py
- 提交触发多个工具的查询:
temporal workflow execute --type AgentWorkflow --task-queue gemini-agent \
--input '"are there any weather alerts where I am?"'
一旦工具调用完成并且计时器开始运行,就终止工作进程(
Ctrl-C在工作终端,或kill %1如果在后台运行)。重新启动工作线程:
uv run durable_agent_worker.py
Temporal 重播工作流程历史记录。已完成的 LLM 调用和工具调用是 不 重新执行 - 他们的结果立即从历史记录(事件日志)中重播,计时器恢复,并且工作流程成功完成。
更进一步 #
该集成支持的内容超出了本教程的范围。请参阅 插件文档 详情:
- 流媒体。 使用
generate_content_stream像往常一样。要让外部使用者(聊天 UI)在工作流持久运行时实时观察块,请设置TemporalAsyncClient(streaming_topic=...)并主持一个WorkflowStream在工作流程中。 - MCP。 在工作线程上注册客户端 MCP 服务器
GoogleGenAIPlugin(mcp_servers={...})并在工作流程中按名称引用它TemporalMcpClientSession。工具发现和调用作为针对池化工作端连接的活动运行。 - 顶点人工智能。 通行证
vertexai=True对于工人双方genai.Client和工作流程端TemporalAsyncClient, 设置project和location明确地在工作流程端,因此重放保持确定性。