MCP Agent 集成 Temporal 与 OpenTelemetry实现可观测的工作流执行引擎与链路追踪【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent导读本文以仓库中的examples/tracing/temporal示例为核心完整讲解如何在 mcp-agent 中把Temporal 作为执行引擎Execution Engine来运行 Agent 工作流并通过OpenTelemetryOTLP将追踪数据导出到 Jaeger 进行可视化分析。读完本文你将掌握Temporal 本地开发服务器的搭建、Temporal 与 MCP Agent 的完整配置、workflow/workflow_run工作流的编写方式、Worker 与客户端分离的运行模型以及 OTLP 文件导出器与 Jaeger Collector 的链路追踪接入方法。一、示例概览为什么需要“Temporal 追踪”examples/tracing/temporal/是 mcp-agent 仓库中展示可观测 Agent 工作流的官方示例。它解决的问题是当 Agent 工作流跑在分布式、可重放的 Temporal 引擎上时如何把每次 LLM 调用、工具调用、活动Activity执行串成一条完整的 trace从而在 LLM 应用失联或失败时能够定位问题。该目录完整内容如下文件作用README.md示例的运行说明与前置条件main.py创建MCPApp(nametemporal_traces_example)作为全局应用入口basic.py定义SimpleWorkflow并启动执行run_worker.py启动 Temporal Worker注册全部工作流与活动workflows.py统一导入工作流模块便于 Worker 注册mcp_agent.config.yaml核心配置执行引擎、Temporal、MCP Server、OpenTelemetrymcp_agent.secrets.yaml.exampleAPI Key 等敏感信息模板requirements.txt依赖mcp-agent本地源码与temporalio[opentelemetry]二、前置条件与环境准备根据 README运行该示例需要Python 3.10UV包管理器仓库示例统一使用uv安装与运行一个正在运行的 Temporal Server启动方式见下文本地 Jaeger 安装用于接收 OTLP trace 数据建议使用 Jaeger 官方本地运行方式如 Docker 一键启动 All-in-One此外依赖清单 requirements.txt 中还专门声明了temporalio[opentelemetry]这个可选依赖组——Temporal Python SDK 的 OpenTelemetry 支持正是依赖该组件提供的TracingInterceptor这是本示例链路追踪能力的底层来源。三、搭建本地 Temporal 开发服务器在 README 中官方推荐的本地启动方式是使用 Temporal CLI安装 Temporal CLI参考 Temporal 官方 CLI 安装文档。启动本地开发服务器temporal server start-dev该命令会在localhost:7233启动 Temporal Server这也是 mcp_agent.config.yaml 中配置的默认地址并附带一个default命名空间。通过浏览器访问Temporal Web UIhttp://localhost:8233来监控工作流执行状态、查看历史事件History、工作流 ID 与运行结果。四、核心配置详解mcp_agent.config.yaml示例的完整配置如下原样来自 mcp_agent.config.yamlJSON Schema 位于 schema/mcp-agent.config.schema.json# Configuration for the Temporal workflow example $schema: ../../schema/mcp-agent.config.schema.json # Set the execution engine to Temporal execution_engine: temporal # Temporal settings temporal: host: localhost:7233 # Default Temporal server address namespace: default # Default Temporal namespace task_queue: mcp-agent # Task queue for workflows and activities max_concurrent_activities: 10 # Maximum number of concurrent activities rpc_metadata: X-Client-Name: mcp-agent # Logger settings logger: transports: [console, file] level: debug progress_display: false path_settings: path_pattern: logs/mcp-agent-{unique_id}.jsonl unique_id: timestamp # Options: timestamp or session_id timestamp_format: %Y%m%d_%H%M%S mcp: servers: fetch: command: uvx args: [mcp-server-fetch] description: Fetch content at URLs from the world wide web filesystem: command: npx args: [ -y, modelcontextprotocol/server-filesystem, # Current directory will be added by the code ] description: Read and write files on the filesystem openai: # Secrets (API keys, etc.) are stored in an mcp_agent.secrets.yaml file which can be gitignored default_model: gpt-4o-mini otel: enabled: true exporters: - file - otlp: endpoint: http://localhost:4318/v1/traces service_name: TemporalTracingExample4.1execution_engine: temporal这是把 mcp-agent 从默认执行模型切换到 Temporal 的关键开关。设置后应用会实例化TemporalExecutor源码位于 src/mcp_agent/executor/temporal/init.py它以enginetemporal注册把所有workflow当作 Temporal Workflow、所有workflow_task当作 Temporal Activity 来执行。4.2temporal段参数说明对照源码中TemporalSettings模型src/mcp_agent/config.py该段支持的字段如下配置项示例中的值默认值说明hostlocalhost:7233必填Temporal Server 地址即temporal server start-dev的监听地址namespacedefaultdefaultTemporal 命名空间api_key—NoneTemporal Cloud 的 API Key本地开发无需tls—false是否启用 TLS本地开发保持默认task_queuemcp-agent必填工作流与活动使用的任务队列Worker 与客户端必须一致max_concurrent_activities10None最大并发活动数从源码看它会创建一个asyncio.Semaphore限制活动并发src/mcp_agent/executor/temporal/init.pytimeout_seconds—60活动执行的超时时间秒会映射为 Temporal 的schedule_to_close_timeoutrpc_metadataX-Client-Name: mcp-agentNone随 RPC 请求携带的元数据头id_reuse_policy—allow_duplicate工作流 ID 复用策略可选allow_duplicate、allow_duplicate_failed_only、reject_duplicate、terminate_if_runningworkflow_task_modules—[]创建 Worker 前需要额外导入的模块路径列表用于注册更多活动4.3otel段OpenTelemetry 追踪配置示例同时启用了文件导出器与OTLP 导出器是“Temporal 追踪”的核心otel: enabled: true exporters: - file - otlp: endpoint: http://localhost:4318/v1/traces service_name: TemporalTracingExample对照 src/mcp_agent/config.py 中的OpenTelemetrySettingsenabled默认false示例显式打开启用后TemporalExecutor.ensure_client()会给 Temporal 客户端挂上tracingio.contrib.opentelemetry的TracingInterceptor见 src/mcp_agent/executor/temporal/init.pyexporters支持同时启用多个导出器写法有“字符串形式”如console、file、otlp和“键值映射形式”如otlp: {endpoint: ...}。OTLPExporterSettings支持endpoint与headers两个字段src/mcp_agent/config.pyFileExporterSettings支持path与path_settingsservice_name默认mcp-agent示例改为TemporalTracingExample在 Jaeger 中以此区分服务另有sample_rate默认1.0表示全量采样与service_instance_id、service_version等可选字段。注意OTLP 导出器的endpoint指向 Jaeger Collector 的 HTTP/gRPC trace 接收地址本例为http://localhost:4318/v1/traces需要在运行前确保 Jaeger 已在本机启动并监听该端口。4.4 敏感信息mcp_agent.secrets.yamlopenai.default_model使用了gpt-4o-mini而对应的 API Key 存放在独立的 mcp_agent.secrets.yaml.example 中示例中为sk-your-openai-key占位符实际使用时将其复制为mcp_agent.secrets.yaml并填入真实 Key可加入.gitignore防止泄露。默认模型也可按需切换为o3-mini等 OpenAI 模型。4.5 MCP Serverfetch 与 filesystem示例工作流会用到两个 MCP Serverfetch通过uvx mcp-server-fetch启动用于抓取网页内容filesystem通过npx -y modelcontextprotocol/server-filesystem启动提供文件系统读写能力。注意其args中并未写死路径——由代码在运行时动态追加当前工作目录见下文basic.py的分析。五、源码走读工作流、Worker 与执行器5.1 应用入口main.pymain.py 只有一行核心逻辑创建MCPApp实例配置来源为同目录下的mcp_agent.config.yamlfrom mcp_agent.app import MCPApp # Create the app, using mcp_agent.config.yaml for configuration app MCPApp(nametemporal_traces_example)这个app是客户端脚本与 Worker 脚本的公共入口同时负责承载app.workflow装饰器注册的工作流。5.2 定义并启动工作流basic.pybasic.py 展示了 mcp-agent 声明式工作流的最小完整形态from mcp_agent.agents.agent import Agent from mcp_agent.executor.temporal import TemporalExecutor from mcp_agent.executor.workflow import Workflow, WorkflowResult from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM from main import app app.workflow class SimpleWorkflow(Workflow[str]): A simple workflow that demonstrates the basic structure of a Temporal workflow. app.workflow_run async def run(self, input: str) - WorkflowResult[str]: finder_agent Agent( namefinder, instructionYou are a helpful assistant., server_names[fetch, filesystem], ) context app.context context.config.mcp.servers[filesystem].args.extend([os.getcwd()]) async with finder_agent: finder_llm await finder_agent.attach_llm(OpenAIAugmentedLLM) result await finder_llm.generate_str(messageinput) return WorkflowResult(valueresult)要点拆解app.workflow把SimpleWorkflow注册为 Temporal Workflowapp.workflow_run标记其run方法为工作流主入口入参类型为str返回WorkflowResult[str]工作流内部构建名为finder的 Agent绑定fetch与filesystem两个 MCP Server并通过OpenAIAugmentedLLM执行一次 LLM 生成关键细节filesystemServer 的工作目录由代码在运行期注入——context.config.mcp.servers[filesystem].args.extend([os.getcwd()])把当前目录追加为npx启动参数因此配置文件里无需硬编码路径main()中通过app.run()进入应用上下文取出TemporalExecutor调用start_workflow(SimpleWorkflow, Print the first 2 paragraphs of https://modelcontextprotocol.io/introduction)发起工作流再用handle.result()阻塞等待最终结果并打印。从TemporalExecutor.start_workflow的实现src/mcp_agent/executor/temporal/init.py可以看到其内部行为根据类型名从app.workflows找到工作流类 → 检查run()签名并绑定参数 → 生成默认工作流 ID{workflow_type}-{uuid()}→ 使用配置中的task_queue与id_reuse_policy调用 Temporal 客户端start_workflow。若要同步等待可传入wait_for_resultTrue对应execute_workflow便捷方法。5.3 启动 Workerrun_worker.pyTemporal 采用“客户端提交、Worker 执行”的模型因此运行工作流前必须先启动 Worker。 run_worker.py 的核心逻辑只有几行import asyncio import logging from main import app import workflows # noqa: F401 from mcp_agent.executor.temporal import create_temporal_worker_for_app logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) async def main(): async with create_temporal_worker_for_app(app) as worker: await worker.run() if __name__ __main__: asyncio.run(main())其中import workflows的作用是提前导入工作流模块确保SimpleWorkflow在 Worker 创建前完成注册。create_temporal_worker_for_appsrc/mcp_agent/executor/temporal/init.py是一个异步上下文管理器它负责启动应用并校验执行器确为TemporalExecutor预加载默认的 LLM 增强模块augmented_llm_openai等以及配置中声明的workflow_task_modules注册 Agent 相关的系统活动call_tool_task、list_tools_task、get_prompt_task、initialize_aggregator_task等与系统级活动mcp_forward_log、mcp_request_user_input、mcp_relay_notify、mcp_relay_request从活动注册表中收集全部活动从app.workflows收集工作流构建 TemporalWorkerWorker 使用ContextPropagationInterceptor保证执行上下文在 Client、Workflow、Activity 之间传递。5.4 注册聚合模块workflows.pyworkflows.py 只是简单的再导出用于集中注册from basic import SimpleWorkflow # noqa: F401六、链路追踪的原理与数据流向该示例的追踪体系由三层构成Temporal 侧当otel.enabled: true时TemporalExecutor.ensure_client()在连接 Temporal 客户端时会注入TracingInterceptor()与ContextPropagationInterceptor()src/mcp_agent/executor/temporal/init.py。TracingInterceptor来自temporalio.contrib.opentelemetry负责把 Workflow 启动、Activity 调度等 Temporal 调用接入 OpenTelemetry spanmcp-agent 侧Agent 的 LLM 调用、工具调用同样通过项目内置的 telemetry 链路产生 span与 Temporal 的 span 汇聚到同一 trace 中导出侧otel.exporters中的file导出器把 trace 写入本地文件默认日志路径格式为logs/mcp-agent-{unique_id}.jsonl见配置中logger.path_settingsotlp导出器则把 trace 发送到http://localhost:4318/v1/traces交给 Jaeger Collector最终在 Jaeger UI 中按service_nameTemporalTracingExample聚合展示。此外ContextPropagationInterceptor实现于 src/mcp_agent/executor/temporal/interceptor.py会在客户端发起的start_workflow、signal_workflow、query_workflow等调用上把 Execution ID 写入头部Workflow 与 Activity 入口再取回并设置到上下文确保一条 trace 内所有调用链可关联。若你只是想把 trace 落盘或打到控制台可以把exporters简化为[file]或[console]——配置模型本身兼容多种写法src/mcp_agent/config.py。七、完整运行步骤第 1 步安装依赖uv pip install -r requirements.txt该命令会安装本地源码版mcp-agentrequirements.txt中以mcp-agent file://../../../指向仓库根以及temporalio[opentelemetry]。第 2 步启动 Temporal Servertemporal server start-dev确认localhost:7233可访问并可打开http://localhost:8233查看 Temporal Web UI。第 3 步配置并启动 Jaeger Collector在本地运行 Jaeger并确保 mcp_agent.config.yaml 中的otel.exporters包含指向http://localhost:4318/v1/traces的 OTLP 导出器示例已配置好。第 4 步启动 Worker独立终端uv run run_worker.pyWorker 会把所有已注册的工作流与活动登记到 Temporal并开始轮询任务队列mcp-agent。第 5 步运行工作流客户端另一终端uv run basic.py程序将启动SimpleWorkflow让finderAgent 借助fetch与filesystem两个 MCP Server 抓取并处理指定 URL 的正文前两段最后打印WorkflowResult。第 6 步观察结果Temporal Web UI查看工作流历史事件、执行状态与重试记录Jaeger UI按TemporalTracingExample服务名检索 trace查看 LLM 调用、Activity 执行的耗时瀑布图日志文件logs/目录下会生成 JSONL 格式的 trace/日志文件可用仓库 scripts/event_viewer.py、scripts/event_summary.py 等脚本做离线分析。八、常见问题与排查建议现象可能原因与排查思路App executor is not a TemporalExecutorexecution_engine未设置为temporal或配置加载的不是本示例的 mcp_agent.config.yaml工作流一直 Pending无 Worker 消费忘记启动uv run run_worker.py或客户端与 Worker 的task_queue不一致必须同为mcp-agent工作流立即失败mcp_agent.secrets.yaml未配置有效 OpenAI API Key或fetch/filesystem对应的uvx/npx命令不可用Jaeger 中看不到 trace检查otel.enabled是否为true、Jaeger Collector 是否监听4318端口、endpoint路径是否完整/v1/tracesfilesystemServer 无权限读取目录确认以预期工作目录启动客户端basic.py会把该目录动态追加到 Server 参数中九、延伸阅读若想了解 Temporal 作为执行引擎的更多模式并行、编排、人机交互等可参考 docs/advanced/temporal.mdx 与 examples/temporal仓库中还有基于不同追踪后端的姊妹示例包括 agent、llm、mcp 与 langfuse可对照理解 mcp-agent 可观测性体系的多样性OpenTelemetry 配置模型的完整字段导出器写法、service_name、sample_rate等定义于 src/mcp_agent/config.pyTemporal 配置模型位于 src/mcp_agent/config.py。【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MCP Agent 集成 Temporal 与 OpenTelemetry：实现可观测的工作流执行引擎与链路追踪
MCP Agent 集成 Temporal 与 OpenTelemetry实现可观测的工作流执行引擎与链路追踪【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent导读本文以仓库中的examples/tracing/temporal示例为核心完整讲解如何在 mcp-agent 中把Temporal 作为执行引擎Execution Engine来运行 Agent 工作流并通过OpenTelemetryOTLP将追踪数据导出到 Jaeger 进行可视化分析。读完本文你将掌握Temporal 本地开发服务器的搭建、Temporal 与 MCP Agent 的完整配置、workflow/workflow_run工作流的编写方式、Worker 与客户端分离的运行模型以及 OTLP 文件导出器与 Jaeger Collector 的链路追踪接入方法。一、示例概览为什么需要“Temporal 追踪”examples/tracing/temporal/是 mcp-agent 仓库中展示可观测 Agent 工作流的官方示例。它解决的问题是当 Agent 工作流跑在分布式、可重放的 Temporal 引擎上时如何把每次 LLM 调用、工具调用、活动Activity执行串成一条完整的 trace从而在 LLM 应用失联或失败时能够定位问题。该目录完整内容如下文件作用README.md示例的运行说明与前置条件main.py创建MCPApp(nametemporal_traces_example)作为全局应用入口basic.py定义SimpleWorkflow并启动执行run_worker.py启动 Temporal Worker注册全部工作流与活动workflows.py统一导入工作流模块便于 Worker 注册mcp_agent.config.yaml核心配置执行引擎、Temporal、MCP Server、OpenTelemetrymcp_agent.secrets.yaml.exampleAPI Key 等敏感信息模板requirements.txt依赖mcp-agent本地源码与temporalio[opentelemetry]二、前置条件与环境准备根据 README运行该示例需要Python 3.10UV包管理器仓库示例统一使用uv安装与运行一个正在运行的 Temporal Server启动方式见下文本地 Jaeger 安装用于接收 OTLP trace 数据建议使用 Jaeger 官方本地运行方式如 Docker 一键启动 All-in-One此外依赖清单 requirements.txt 中还专门声明了temporalio[opentelemetry]这个可选依赖组——Temporal Python SDK 的 OpenTelemetry 支持正是依赖该组件提供的TracingInterceptor这是本示例链路追踪能力的底层来源。三、搭建本地 Temporal 开发服务器在 README 中官方推荐的本地启动方式是使用 Temporal CLI安装 Temporal CLI参考 Temporal 官方 CLI 安装文档。启动本地开发服务器temporal server start-dev该命令会在localhost:7233启动 Temporal Server这也是 mcp_agent.config.yaml 中配置的默认地址并附带一个default命名空间。通过浏览器访问Temporal Web UIhttp://localhost:8233来监控工作流执行状态、查看历史事件History、工作流 ID 与运行结果。四、核心配置详解mcp_agent.config.yaml示例的完整配置如下原样来自 mcp_agent.config.yamlJSON Schema 位于 schema/mcp-agent.config.schema.json# Configuration for the Temporal workflow example $schema: ../../schema/mcp-agent.config.schema.json # Set the execution engine to Temporal execution_engine: temporal # Temporal settings temporal: host: localhost:7233 # Default Temporal server address namespace: default # Default Temporal namespace task_queue: mcp-agent # Task queue for workflows and activities max_concurrent_activities: 10 # Maximum number of concurrent activities rpc_metadata: X-Client-Name: mcp-agent # Logger settings logger: transports: [console, file] level: debug progress_display: false path_settings: path_pattern: logs/mcp-agent-{unique_id}.jsonl unique_id: timestamp # Options: timestamp or session_id timestamp_format: %Y%m%d_%H%M%S mcp: servers: fetch: command: uvx args: [mcp-server-fetch] description: Fetch content at URLs from the world wide web filesystem: command: npx args: [ -y, modelcontextprotocol/server-filesystem, # Current directory will be added by the code ] description: Read and write files on the filesystem openai: # Secrets (API keys, etc.) are stored in an mcp_agent.secrets.yaml file which can be gitignored default_model: gpt-4o-mini otel: enabled: true exporters: - file - otlp: endpoint: http://localhost:4318/v1/traces service_name: TemporalTracingExample4.1execution_engine: temporal这是把 mcp-agent 从默认执行模型切换到 Temporal 的关键开关。设置后应用会实例化TemporalExecutor源码位于 src/mcp_agent/executor/temporal/init.py它以enginetemporal注册把所有workflow当作 Temporal Workflow、所有workflow_task当作 Temporal Activity 来执行。4.2temporal段参数说明对照源码中TemporalSettings模型src/mcp_agent/config.py该段支持的字段如下配置项示例中的值默认值说明hostlocalhost:7233必填Temporal Server 地址即temporal server start-dev的监听地址namespacedefaultdefaultTemporal 命名空间api_key—NoneTemporal Cloud 的 API Key本地开发无需tls—false是否启用 TLS本地开发保持默认task_queuemcp-agent必填工作流与活动使用的任务队列Worker 与客户端必须一致max_concurrent_activities10None最大并发活动数从源码看它会创建一个asyncio.Semaphore限制活动并发src/mcp_agent/executor/temporal/init.pytimeout_seconds—60活动执行的超时时间秒会映射为 Temporal 的schedule_to_close_timeoutrpc_metadataX-Client-Name: mcp-agentNone随 RPC 请求携带的元数据头id_reuse_policy—allow_duplicate工作流 ID 复用策略可选allow_duplicate、allow_duplicate_failed_only、reject_duplicate、terminate_if_runningworkflow_task_modules—[]创建 Worker 前需要额外导入的模块路径列表用于注册更多活动4.3otel段OpenTelemetry 追踪配置示例同时启用了文件导出器与OTLP 导出器是“Temporal 追踪”的核心otel: enabled: true exporters: - file - otlp: endpoint: http://localhost:4318/v1/traces service_name: TemporalTracingExample对照 src/mcp_agent/config.py 中的OpenTelemetrySettingsenabled默认false示例显式打开启用后TemporalExecutor.ensure_client()会给 Temporal 客户端挂上tracingio.contrib.opentelemetry的TracingInterceptor见 src/mcp_agent/executor/temporal/init.pyexporters支持同时启用多个导出器写法有“字符串形式”如console、file、otlp和“键值映射形式”如otlp: {endpoint: ...}。OTLPExporterSettings支持endpoint与headers两个字段src/mcp_agent/config.pyFileExporterSettings支持path与path_settingsservice_name默认mcp-agent示例改为TemporalTracingExample在 Jaeger 中以此区分服务另有sample_rate默认1.0表示全量采样与service_instance_id、service_version等可选字段。注意OTLP 导出器的endpoint指向 Jaeger Collector 的 HTTP/gRPC trace 接收地址本例为http://localhost:4318/v1/traces需要在运行前确保 Jaeger 已在本机启动并监听该端口。4.4 敏感信息mcp_agent.secrets.yamlopenai.default_model使用了gpt-4o-mini而对应的 API Key 存放在独立的 mcp_agent.secrets.yaml.example 中示例中为sk-your-openai-key占位符实际使用时将其复制为mcp_agent.secrets.yaml并填入真实 Key可加入.gitignore防止泄露。默认模型也可按需切换为o3-mini等 OpenAI 模型。4.5 MCP Serverfetch 与 filesystem示例工作流会用到两个 MCP Serverfetch通过uvx mcp-server-fetch启动用于抓取网页内容filesystem通过npx -y modelcontextprotocol/server-filesystem启动提供文件系统读写能力。注意其args中并未写死路径——由代码在运行时动态追加当前工作目录见下文basic.py的分析。五、源码走读工作流、Worker 与执行器5.1 应用入口main.pymain.py 只有一行核心逻辑创建MCPApp实例配置来源为同目录下的mcp_agent.config.yamlfrom mcp_agent.app import MCPApp # Create the app, using mcp_agent.config.yaml for configuration app MCPApp(nametemporal_traces_example)这个app是客户端脚本与 Worker 脚本的公共入口同时负责承载app.workflow装饰器注册的工作流。5.2 定义并启动工作流basic.pybasic.py 展示了 mcp-agent 声明式工作流的最小完整形态from mcp_agent.agents.agent import Agent from mcp_agent.executor.temporal import TemporalExecutor from mcp_agent.executor.workflow import Workflow, WorkflowResult from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM from main import app app.workflow class SimpleWorkflow(Workflow[str]): A simple workflow that demonstrates the basic structure of a Temporal workflow. app.workflow_run async def run(self, input: str) - WorkflowResult[str]: finder_agent Agent( namefinder, instructionYou are a helpful assistant., server_names[fetch, filesystem], ) context app.context context.config.mcp.servers[filesystem].args.extend([os.getcwd()]) async with finder_agent: finder_llm await finder_agent.attach_llm(OpenAIAugmentedLLM) result await finder_llm.generate_str(messageinput) return WorkflowResult(valueresult)要点拆解app.workflow把SimpleWorkflow注册为 Temporal Workflowapp.workflow_run标记其run方法为工作流主入口入参类型为str返回WorkflowResult[str]工作流内部构建名为finder的 Agent绑定fetch与filesystem两个 MCP Server并通过OpenAIAugmentedLLM执行一次 LLM 生成关键细节filesystemServer 的工作目录由代码在运行期注入——context.config.mcp.servers[filesystem].args.extend([os.getcwd()])把当前目录追加为npx启动参数因此配置文件里无需硬编码路径main()中通过app.run()进入应用上下文取出TemporalExecutor调用start_workflow(SimpleWorkflow, Print the first 2 paragraphs of https://modelcontextprotocol.io/introduction)发起工作流再用handle.result()阻塞等待最终结果并打印。从TemporalExecutor.start_workflow的实现src/mcp_agent/executor/temporal/init.py可以看到其内部行为根据类型名从app.workflows找到工作流类 → 检查run()签名并绑定参数 → 生成默认工作流 ID{workflow_type}-{uuid()}→ 使用配置中的task_queue与id_reuse_policy调用 Temporal 客户端start_workflow。若要同步等待可传入wait_for_resultTrue对应execute_workflow便捷方法。5.3 启动 Workerrun_worker.pyTemporal 采用“客户端提交、Worker 执行”的模型因此运行工作流前必须先启动 Worker。 run_worker.py 的核心逻辑只有几行import asyncio import logging from main import app import workflows # noqa: F401 from mcp_agent.executor.temporal import create_temporal_worker_for_app logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) async def main(): async with create_temporal_worker_for_app(app) as worker: await worker.run() if __name__ __main__: asyncio.run(main())其中import workflows的作用是提前导入工作流模块确保SimpleWorkflow在 Worker 创建前完成注册。create_temporal_worker_for_appsrc/mcp_agent/executor/temporal/init.py是一个异步上下文管理器它负责启动应用并校验执行器确为TemporalExecutor预加载默认的 LLM 增强模块augmented_llm_openai等以及配置中声明的workflow_task_modules注册 Agent 相关的系统活动call_tool_task、list_tools_task、get_prompt_task、initialize_aggregator_task等与系统级活动mcp_forward_log、mcp_request_user_input、mcp_relay_notify、mcp_relay_request从活动注册表中收集全部活动从app.workflows收集工作流构建 TemporalWorkerWorker 使用ContextPropagationInterceptor保证执行上下文在 Client、Workflow、Activity 之间传递。5.4 注册聚合模块workflows.pyworkflows.py 只是简单的再导出用于集中注册from basic import SimpleWorkflow # noqa: F401六、链路追踪的原理与数据流向该示例的追踪体系由三层构成Temporal 侧当otel.enabled: true时TemporalExecutor.ensure_client()在连接 Temporal 客户端时会注入TracingInterceptor()与ContextPropagationInterceptor()src/mcp_agent/executor/temporal/init.py。TracingInterceptor来自temporalio.contrib.opentelemetry负责把 Workflow 启动、Activity 调度等 Temporal 调用接入 OpenTelemetry spanmcp-agent 侧Agent 的 LLM 调用、工具调用同样通过项目内置的 telemetry 链路产生 span与 Temporal 的 span 汇聚到同一 trace 中导出侧otel.exporters中的file导出器把 trace 写入本地文件默认日志路径格式为logs/mcp-agent-{unique_id}.jsonl见配置中logger.path_settingsotlp导出器则把 trace 发送到http://localhost:4318/v1/traces交给 Jaeger Collector最终在 Jaeger UI 中按service_nameTemporalTracingExample聚合展示。此外ContextPropagationInterceptor实现于 src/mcp_agent/executor/temporal/interceptor.py会在客户端发起的start_workflow、signal_workflow、query_workflow等调用上把 Execution ID 写入头部Workflow 与 Activity 入口再取回并设置到上下文确保一条 trace 内所有调用链可关联。若你只是想把 trace 落盘或打到控制台可以把exporters简化为[file]或[console]——配置模型本身兼容多种写法src/mcp_agent/config.py。七、完整运行步骤第 1 步安装依赖uv pip install -r requirements.txt该命令会安装本地源码版mcp-agentrequirements.txt中以mcp-agent file://../../../指向仓库根以及temporalio[opentelemetry]。第 2 步启动 Temporal Servertemporal server start-dev确认localhost:7233可访问并可打开http://localhost:8233查看 Temporal Web UI。第 3 步配置并启动 Jaeger Collector在本地运行 Jaeger并确保 mcp_agent.config.yaml 中的otel.exporters包含指向http://localhost:4318/v1/traces的 OTLP 导出器示例已配置好。第 4 步启动 Worker独立终端uv run run_worker.pyWorker 会把所有已注册的工作流与活动登记到 Temporal并开始轮询任务队列mcp-agent。第 5 步运行工作流客户端另一终端uv run basic.py程序将启动SimpleWorkflow让finderAgent 借助fetch与filesystem两个 MCP Server 抓取并处理指定 URL 的正文前两段最后打印WorkflowResult。第 6 步观察结果Temporal Web UI查看工作流历史事件、执行状态与重试记录Jaeger UI按TemporalTracingExample服务名检索 trace查看 LLM 调用、Activity 执行的耗时瀑布图日志文件logs/目录下会生成 JSONL 格式的 trace/日志文件可用仓库 scripts/event_viewer.py、scripts/event_summary.py 等脚本做离线分析。八、常见问题与排查建议现象可能原因与排查思路App executor is not a TemporalExecutorexecution_engine未设置为temporal或配置加载的不是本示例的 mcp_agent.config.yaml工作流一直 Pending无 Worker 消费忘记启动uv run run_worker.py或客户端与 Worker 的task_queue不一致必须同为mcp-agent工作流立即失败mcp_agent.secrets.yaml未配置有效 OpenAI API Key或fetch/filesystem对应的uvx/npx命令不可用Jaeger 中看不到 trace检查otel.enabled是否为true、Jaeger Collector 是否监听4318端口、endpoint路径是否完整/v1/tracesfilesystemServer 无权限读取目录确认以预期工作目录启动客户端basic.py会把该目录动态追加到 Server 参数中九、延伸阅读若想了解 Temporal 作为执行引擎的更多模式并行、编排、人机交互等可参考 docs/advanced/temporal.mdx 与 examples/temporal仓库中还有基于不同追踪后端的姊妹示例包括 agent、llm、mcp 与 langfuse可对照理解 mcp-agent 可观测性体系的多样性OpenTelemetry 配置模型的完整字段导出器写法、service_name、sample_rate等定义于 src/mcp_agent/config.pyTemporal 配置模型位于 src/mcp_agent/config.py。【免费下载链接】mcp-agentBuild effective agents using Model Context Protocol and simple workflow patterns项目地址: https://gitcode.com/GitHub_Trending/mc/mcp-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考