Temporal AI 智能体

此演示展示了在 Temporal 工作流（Workflow）中运行的 AI 智能体（Agent）的多轮对话。智能体的目的是收集信息以实现目标，并在此过程中运行工具。该智能体支持原生工具和模型上下文协议（Model Context Protocol, MCP）工具，允许它与外部服务交互。

默认情况下，智能体以单智能体模式运行，专注于一个特定目标。它还支持实验性的多智能体/多目标模式，用户可以在不同智能体类型之间选择并在对话期间切换。

目标按类别（金融、人力资源、旅行、电子商务等）组织在 /goals/ 目录中，并利用原生和 MCP 工具。

AI 将提供澄清并询问实现该目标所需的任何缺失信息。您可以配置它使用 LiteLLM 支持的任何大语言模型（LLM），包括：

• OpenAI 模型 (GPT-4, GPT-3.5)
• Anthropic Claude 模型
• Google Gemini 模型
• Deepseek 模型
• Ollama 模型 (本地)
• 以及更多！

观看演示视频（5 分钟 YouTube 视频）[链接] 对于理解交互方式非常有帮助。

多智能体演示视频

在此处查看多智能体执行的实时演示 here。

为什么选择 Temporal？

市面上有很多 AI 和智能体 AI 工具，而且还在不断增加。但为什么要用 Temporal？Temporal 为该系统的可靠性、状态管理、我们非常喜欢的代码优先方法、内置的可观测性以及简单的错误处理提供了支持。 更多信息，请查看 architecture-decisions。

什么是“智能体 AI"？

这是智能体框架的关键要素：

1. 系统可以完成的目标，由可执行单个步骤的工具组成
2. 智能体循环 - 执行 LLM，执行工具，并从外部来源（如人类）获取输入：重复直到目标完成
3. 支持需要输入和批准的工具调用
4. 使用 LLM 在调用“真实”LLM 之前检查人类输入的相关性
5. 使用 LLM 总结和压缩对话历史
6. 提示词构建包含系统提示词、对话历史和工具元数据 - 发送给 LLM 以创建用户问题和确认
7. 理想情况下具有高持久性（本系统中通过 Temporal 工作流和活动（Activities）实现）

深入了解，请查看 架构指南。

🔧 MCP 工具调用支持

该智能体充当 MCP（模型上下文协议）客户端，支持与外部服务和工具的无缝集成。系统支持两种类型的工具：

• 原生工具：直接在代码库中实现的自定义工具（在 /tools/ 中）
• MCP 工具：通过模型上下文协议（MCP）服务器访问的外部工具，如 Stripe、数据库或 API。配置见 the Setup guide
• 在 .env 中设置 AGENT_GOAL=goal_food_ordering 且 SHOW_CONFIRM=False 作为调用 MCP 工具（Stripe）的目标示例。

设置与配置

详细说明请参见 the Setup guide。基本配置只需要两个环境变量：

LLM_MODEL=openai/gpt-4o  # or any other model supported by LiteLLM
LLM_KEY=your-api-key-here

自定义交互与工具

请参见 添加目标和工具的指南。

系统支持 MCP（模型上下文协议），便于与外部服务集成。MCP 服务器配置在 shared/mcp_config.py 中管理，目标按类别组织在 /goals/ 目录中。

架构

请参见 架构指南。

测试

该项目使用 Temporal 的测试框架为工作流和活动包含全面的测试：

# Install dependencies including test dependencies
uv sync

# Run all tests
uv run pytest

# Run with time-skipping for faster execution
uv run pytest --workflow-environment=time-skipping

测试覆盖范围：

• ✅ 工作流测试：AgentGoalWorkflow 信号、查询、状态管理

• ✅ 活动测试：ToolActivities、LLM 集成（模拟）、环境配置

• ✅ 集成测试：端到端工作流和活动执行

• 快速开始：testing.md - 运行测试的简单命令

• 综合指南：tests/README.md - 详细的测试文档、模式和最佳实践

开发

要为此项目做贡献，请参见 contributing.md。

启动 Temporal 服务器和 API 服务器，请参见 setup。

生产化与添加功能

• 在生产环境中，我需要确保有效载荷数据存储在别处（例如 S3 或 NoSQL 数据库 - claim-check 模式），或者进行“垃圾回收”。如果没有这些技术，长对话会填满工作流的对话历史，并开始突破 Temporal 事件历史记录负载限制。
• 单个工作器可以轻松支持同时运行的许多智能体工作流（聊天）。目前每次的工作流 ID 都相同，因此它将一次只运行一个智能体。要运行多个智能体，您可以每次都使用不同的工作流 ID（例如通过使用 UUID 或时间戳）。
• 也许 UI 应该显示何时正在重试 LLM 响应（即由于 LLM 提供不良输出而导致的活动重试尝试）
• 该项目现在包含针对工作流和活动的全面测试！参见测试指南。

有关我们要做的事情（或你可以贡献的事情）的更多详细信息，请参见 todo。

有关您可以添加功能的更多方式，请参见 添加目标和工具的指南。

启用指南（Temporal 员工的内部资源）

请查看这里的 幻灯片 和 启用指南。

temporal-ai-agent 快速上手指南

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux / macOS / Windows
• 编程语言: Python 3.x
• 包管理工具: uv (用于依赖管理和运行脚本)
• 中间件: 本地或云端的 Temporal Server (需预先启动)
• 大模型服务: 支持通过 LiteLLM 调用的模型
  • 推荐国内开发者使用：Deepseek、Ollama (本地部署)、Google Gemini 等
  • 其他支持：OpenAI (GPT-4/3.5)、Anthropic Claude 等

安装步骤

1. 克隆项目代码

   git clone <repository-url>
   cd temporal-ai-agent
   

2. 安装依赖 使用 uv 同步项目依赖（包含测试依赖）：

   uv sync
   

3. 配置环境变量 在项目根目录创建 .env 文件，配置基础参数（详细配置请查阅 docs/setup.md）：

   LLM_MODEL=openai/gpt-4o  # 或任何 LiteLLM 支持的模型
   LLM_KEY=your-api-key-here
   

   提示：若使用本地 Ollama 模型，可设置为 ollama/llama3 等。

基本使用

1. 启动服务 确保 Temporal Server 和 API Server 已经运行（具体启动命令请参考 docs/setup.md）。

2. 配置目标与工具 系统支持多种目标分类（finance, HR, travel 等），位于 /goals/ 目录下。 若要测试 MCP 工具调用（例如 Stripe），可在 .env 中添加以下配置：

   AGENT_GOAL=goal_food_ordering
   SHOW_CONFIRM=False
   

3. 运行与验证 项目内置了完善的测试框架，可用于验证工作流和活动逻辑：

   # 运行所有测试
   uv run pytest
   
   # 加速运行（跳过时间等待）
   uv run pytest --workflow-environment=time-skipping
   

   正式运行 Agent 交互的具体命令请参照 docs/setup.md 中的完整操作指引。

---

相关文档

• 架构说明: docs/architecture.md
• 添加新目标与工具: docs/adding-goals-and-tools.md
• MCP 配置: shared/mcp_config.py