Temporal AI Agent

此演示展示了一个运行在 Temporal 工作流（Workflow）中的 AI Agent 进行多轮对话的过程。该 Agent 的目标是收集信息以达成特定目标，并在执行过程中运行各种工具。该 Agent 同时支持原生工具和 MCP (Model Context Protocol) 工具，使其能够与外部服务进行交互。

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

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

AI 将通过澄清问题进行响应，并询问达成目标所需缺失的信息。你可以将其配置为使用 LiteLLM 支持的任何 LLM，包括：

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

观看 演示视频（5分钟 YouTube 视频） 以了解交互方式非常有帮助。

多 Agent 演示视频

点击 此处 查看多 Agent 执行过程。

为什么选择 Temporal？

目前市面上有很多 AI 和 Agentic AI 工具，而且未来还会出现更多。但为什么要选择 Temporal？Temporal 为该系统提供了可靠性、状态管理、我们非常推崇的“代码优先（code-first）”方法、内置的可观测性以及简便的错误处理机制。 更多详情，请查看 architecture-decisions。

什么是“Agentic AI”？

这是一个 Agentic 框架的关键要素：

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

要深入了解这一点，请查看 架构指南。

🔧 MCP 工具调用支持

该 Agent 充当 MCP (Model Context Protocol) 客户端，实现了与外部服务和工具的无缝集成。系统支持两种类型的工具：

• 原生工具 (Native Tools)：直接在代码库中实现的自定义工具（位于 /tools/ 下）
• MCP 工具：通过 MCP 服务器（如 Stripe、数据库或 API）访问的外部工具。配置信息请参阅 设置指南
• 在 .env 中设置 AGENT_GOAL=goal_food_ordering 并将 SHOW_CONFIRM=False，即可查看调用 MCP 工具 (Stripe) 的目标示例。

设置与配置

详细说明请参阅 设置指南。基本配置仅需两个环境变量：

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

自定义交互与工具

请参阅 添加目标与工具指南。

该系统支持 MCP 以方便集成外部服务。MCP 服务器配置在 shared/mcp_config.py 中管理，目标按类别组织在 /goals/ 目录下。

架构

请参阅 架构指南。

测试

该项目包含使用 Temporal 测试框架对工作流和活动进行的全方位测试：

# 安装依赖（包括测试依赖）
uv sync

# 运行所有测试
uv run pytest

# 开启时间跳跃（time-skipping）以加快执行速度
uv run pytest --workflow-environment=time-skipping

测试覆盖范围：

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

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

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

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

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

开发

如需为本项目做出贡献，请参阅 contributing.md。

启动 Temporal Server 和 API 服务器，请参阅 设置指南。

生产化与功能添加

• 在生产环境中，我需要确保负载数据（payload data）被单独存储（例如在 S3 或 NoSQL 数据库中——即 claim-check 模式）。