Durable Agents (Temporal)

​

When to choose Temporal

​

Enable the Temporal engine

execution_engine: temporal

temporal:
  host: "localhost"
  port: 7233
  namespace: "default"
  task_queue: "mcp-agent"
  max_concurrent_activities: 10

temporal server start-dev
# Web UI: http://localhost:8233  |  gRPC: localhost:7233

​

Run a worker

# examples/temporal/run_worker.py
import asyncio
import logging

import workflows  # noqa: F401  # registers @app.workflow classes
from main import app
from mcp_agent.executor.temporal import create_temporal_worker_for_app

logging.basicConfig(level=logging.INFO)

async def main():
    async with create_temporal_worker_for_app(app) as worker:
        await worker.run()

if __name__ == "__main__":
    asyncio.run(main())

​

Launch workflows (or tools) durably

# examples/temporal/basic.py
async with app.run() as agent_app:
    executor = agent_app.executor  # TemporalExecutor
    handle = await executor.start_workflow(
        "SimpleWorkflow",
        "Print the first 2 paragraphs of https://modelcontextprotocol.io/introduction",
    )
    result = await handle.result()
    print(result)

# examples/temporal/orchestrator.py (excerpt)
@app.async_tool(name="OrchestratorWorkflow")
async def run_orchestrator(task: str, app_ctx: AppContext | None = None) -> str:
    context = app_ctx or app.context
    orchestrator = Orchestrator(
        llm_factory=OpenAIAugmentedLLM,
        available_agents=[finder, writer, proofreader, fact_checker, style_enforcer],
        plan_type="full",
        context=context,
    )
    return await orchestrator.generate_str(task)

async with app.run() as orchestrator_app:
    executor = orchestrator_app.executor
    handle = await executor.start_workflow("OrchestratorWorkflow", task)
    report = await handle.result()

​

Human approvals, pause, and resume

# PauseResumeWorkflow (excerpt)
print(f"Workflow paused. workflow_id={self.id} run_id={self.run_id}")
try:
    await app.context.executor.wait_for_signal(
        signal_name="resume",
        workflow_id=self.id,
        run_id=self.run_id,
        timeout_seconds=60,
    )
except TimeoutError:
    raise ApplicationError("Timed out waiting for resume signal", type="SignalTimeout", non_retryable=True)

return WorkflowResult(value=f"Workflow resumed! {message}")

async with app.run() as agent_app:
    executor = agent_app.executor
    await executor.signal_workflow(
        workflow_name="PauseResumeWorkflow",
        workflow_id="pause-resume-123",
        signal_name="resume",
        payload={"approved_by": "alex"},
    )

​

Nested tools and elicitation

​

Configure workflow-task modules and retry policies

execution_engine: temporal

workflow_task_modules:
  - my_project.temporal_tasks  # importable module path

workflow_task_retry_policies:
  my_project.temporal_tasks.generate_summary:
    maximum_attempts: 1
  mcp_agent.workflows.llm.augmented_llm_openai.OpenAICompletionTasks.request_completion_task:
    maximum_attempts: 2
    non_retryable_error_types:
      - AuthenticationError
      - PermissionDeniedError
      - BadRequestError
      - NotFoundError
      - UnprocessableEntityError
  custom_tasks.*:
    initial_interval: 1.5   # seconds (number, string, or timedelta)
    backoff_coefficient: 1.2
  *:
    maximum_attempts: 3

• workflow_task_modules entries are standard Python import paths; they are imported before the worker begins polling so @workflow_task functions register globally.
• workflow_task_retry_policies accepts exact activity names, module or class suffixes (prefix.suffix), trailing wildcards like custom_tasks.*, or the global *. The most specific match wins.
• Retry intervals accept seconds (1.5), strings ("2"), or timedelta objects.
• Marking error types in non_retryable_error_types prevents Temporal from re-running an activity when the failure is not recoverable (see the Temporal failure reference). For provider SDKs, useful values include:
  • OpenAI/Azure OpenAI: AuthenticationError, PermissionDeniedError, BadRequestError, NotFoundError, UnprocessableEntityError.
  • Anthropic: AuthenticationError, PermissionDeniedError, BadRequestError, NotFoundError, UnprocessableEntityError.
  • Azure AI Inference: HttpResponseError (raised with non-retryable status codes such as 400/401/403/404/422).
  • Google GenAI: InvalidArgument, FailedPrecondition, PermissionDenied, NotFound, Unauthenticated.
• mcp-agent raises WorkflowApplicationError (wrapping Temporal’s ApplicationError when available) for known non-retryable provider failures, so these policies work even if you run without the Temporal extra installed.
• Inspect an activity’s fully-qualified name via func.execution_metadata["activity_name"] or through the Temporal UI history when adding a mapping.
• Temporal matches non_retryable_error_types using the exception class name string you supply (see the RetryPolicy reference). Use the narrowest names possible—overly generic entries such as NotFoundError can suppress legitimate retries if a workflow expects to handle that condition and try again.

​

Operating durable agents

• Temporal Web UI (http://localhost:8233) lets you inspect history, replay workflow code, and emit signals.
• Workflow handles expose describe(), query(), and list() helpers for custom dashboards or integrations.
• Observability: enable OpenTelemetry (otel.enabled: true) to stream spans + logs while Temporal provides event history.
• Deployment: mcp-agent Cloud uses the same configuration. Once deployed, Cloud exposes CLI commands (mcp-agent workflows list, resume, cancel) that call the same signal/query APIs shown above.

​

Deeper dives

• Temporal example suite – side-by-side asyncio vs. Temporal workflows (basic, router, parallel, evaluator-optimizer) plus a detailed README walking through setup.
• Temporal MCP server – exposes durable workflows as MCP tools, demonstrates workflows-resume, and includes a client script for pause/resume flows.
• Temporal tracing example – shows the same code running with Jaeger exports once you flip the execution_engine.

​

Example projects

• examples/temporal – basic workflow, evaluator-optimizer, router, and orchestrator patterns on Temporal.
• examples/mcp_agent_server/temporal – MCP server with durable human approvals, nested servers, and elicitation.
• examples/oauth/pre_authorize – demonstrates pre-authorised credentials for background Temporal workflows.