Execution Engines

Overview

mcp-agent provides two execution engines that determine how agent workflows are executed and managed. Each engine offers different capabilities for reliability, persistence, and deployment scenarios.

asyncio Engine

The asyncio engine runs workflows in-memory using Python’s native async/await capabilities. Characteristics:

In-memory execution
No external dependencies
Fast startup and iteration
Best for development and simple deployments
State lost on process restart

Configuration:

execution_engine: asyncio

Use cases:

Local development
Quick prototyping
Stateless operations
Single-node deployments

Temporal Engine

The Temporal engine provides durable workflow execution with automatic state persistence. Characteristics:

Durable execution across restarts
Automatic retry with exponential backoff
Workflow history and replay
Distributed execution support
Requires Temporal server

Configuration:

execution_engine: temporal
temporal:
  host: "localhost:7233"
  namespace: "default"
  task_queue: "mcp-agent"

Use cases:

Production deployments
Long-running workflows
Critical operations requiring reliability
Multi-node deployments
Workflows requiring pause/resume

📌 Example: The Temporal workflow gallery showcases orchestrator, router, and evaluator/optimizer patterns running on this engine.

Executors

Executors are the runtime components that actually execute workflows within an engine.

AsyncioExecutor

Handles workflow execution for the asyncio engine:

from mcp_agent.executor.executor import AsyncioExecutor

async def greet(name: str) -> str:
    return f"Hi {name}"

executor = AsyncioExecutor()
result = await executor.execute(greet, "Ada")
print(result)  # "Hi Ada"

Features:

Direct Python function execution
Native async/await support
Minimal overhead

See it in action in the basic workflows examples where tasks run entirely in-process.

TemporalExecutor

Manages workflow execution for the Temporal engine:

from mcp_agent.executor.temporal import TemporalExecutor
from mcp_agent.config import TemporalSettings

executor = TemporalExecutor(config=TemporalSettings(
    host="localhost:7233",
    namespace="default",
    task_queue="mcp-agent",
))
handle = await executor.start_workflow("ResearchWorkflow", {"topic": "LLMs"})
result = await handle.result()

Features:

Workflow versioning
Activity retries
Distributed execution
Workflow queries and signals

The examples/oauth/pre_authorize project combines this executor with OAuth-aware workflows.

Choosing an Execution Engine

Development Phase

Use asyncio engine during development:

Fast iteration cycles
No infrastructure requirements
Immediate feedback
Simple debugging

Production Phase

Consider Temporal engine for production:

Workflow reliability
Automatic failure handling
Audit trail via workflow history
Horizontal scaling

Execution Context

Both engines provide an execution context to workflows:

@app.workflow
async def my_workflow(ctx: WorkflowContext, params: dict):
    # Access execution context
    workflow_id = ctx.workflow_id
    run_id = ctx.run_id
    
    # Engine-specific features
    if ctx.engine == "temporal":
        # Temporal-specific operations
        await ctx.sleep(timedelta(hours=1))
    
    return result

Engine-Specific Features

asyncio Features

Direct execution: Workflows run as standard Python functions
Memory state: State maintained in process memory
Simple cancellation: Standard asyncio cancellation

Temporal Features

Workflow replay: Deterministic replay from history
Signals: Send data to running workflows
Queries: Query workflow state without affecting execution
Child workflows: Spawn and manage child workflow instances
Timers: Durable sleep and timeouts
Activities: Retryable units of work

Migration Between Engines

Workflows written for mcp-agent can run on either engine without modification:

# This workflow runs on both engines
@app.workflow
async def portable_workflow(ctx: WorkflowContext, input: dict):
    agent = Agent(
        name="researcher",
        instruction="Research the topic",
        server_names=["fetch"]
    )
    
    async with agent:
        llm = await agent.attach_llm(OpenAIAugmentedLLM)
        result = await llm.generate_str(input["query"])
    
    return result

Performance Considerations

asyncio Engine

Latency: Microseconds for workflow start
Throughput: Limited by single process
Memory: All state in RAM
Reliability: No persistence

Temporal Engine

Latency: Milliseconds for workflow start
Throughput: Horizontally scalable
Memory: State persisted to database
Reliability: Survives crashes and restarts

Configuration Examples

Basic asyncio Setup

execution_engine: asyncio
logger:
  level: info

Production Temporal Setup

execution_engine: temporal
temporal:
  host: "temporal.production.internal:7233"
  namespace: "production"
  task_queue: "agent-workflows"
  worker_count: 4
  max_concurrent_activities: 20

Accessing the executor in an application

MCPApp exposes the active executor and engine selection:

async with app.run() as running_app:
    executor = running_app.executor
    print(executor.execution_engine)  # "asyncio" or "temporal"

You typically call high-level helpers (workflow.execute(), executor.start_workflow) rather than invoking executor methods directly, but the property is available when you need advanced control or diagnostics.

Get Started

MCP Agent SDK

Deployment

Test and Evaluate

Reference

Execution Engines

Overview