Temporal plugin implementation

examples/temporal_plugin/.gitignore

@@ -0,0 +1,93 @@
+# MCP-Agent
+mcp_agent.secrets.yaml
+*.secrets.yaml
+.mcp-agent/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Virtual Environment
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+*.code-workspace
+
+# Vim
+[._]*.s[a-v][a-z]
+[._]*.sw[a-p]
+[._]s[a-rt-v][a-z]
+[._]ss[a-gi-z]
+[._]sw[a-p]
+*~
+
+# Logs
+logs/
+*.log
+*.jsonl
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.hypothesis/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# Local environment variables
+.env.local
+.env.*.local

examples/temporal_plugin/README.md

@@ -0,0 +1,155 @@
+# MCP-Agent with Temporal Plugin
+
+This example demonstrates multiple ways to use the Temporal plugin with MCP-Agent for workflow orchestration.
+
+## Prerequisites
+
+1. **Temporal Server**: Ensure you have a Temporal server running locally:
+   ```bash
+   temporal server start-dev
+   ```
+   This starts a development server at `localhost:7233`
+
+2. **API Keys**: Add your API keys to `mcp_agent.secrets.yaml`:
+   ```yaml
+   OPENAI_API_KEY: "your-key-here"
+   ANTHROPIC_API_KEY: "your-key-here"  # optional
+   ```
+
+3. **Configuration**: Set the execution engine to `temporal` in `mcp_agent.config.yaml`:
+   ```yaml
+   execution_engine: temporal
+
+   temporal:
+     host: "localhost:7233"
+     namespace: "default"
+     task_queue: "mcp-agent"
+   ```
+
+## Usage Methods
+
+### Method 1: Separate Worker and Workflow Files
+
+This approach separates the worker and workflow execution into different processes, useful for distributed systems.
+
+**Step 1: Define your workflow** (`basic_workflow.py`):
+```python
+from temporalio import workflow
+from mcp_agent.agents.agent import Agent
+from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM
+
+@workflow.defn
+class BasicWorkflow:
+    @workflow.run
+    async def run(self, prompt: str) -> str:
+        simple_agent = Agent(
+            name="finder",
+            instruction="You are a helpful agent",
+            server_names=["fetch"],
+        )
+
+        async with simple_agent:
+            llm = await simple_agent.attach_llm(OpenAIAugmentedLLM)
+            result = await llm.generate_str(prompt)
+            return result
+```
+
+**Step 2: Run the worker** (`run_worker.py`):
+```bash
+uv run run_worker.py
+```
+
+**Step 3: Execute the workflow** (in another terminal):
+```bash
+uv run run_basic_workflow.py
+```
+
+### Method 2: Single File Execution (temporal_agent.py)
+
+This approach combines worker and workflow execution in a single file, ideal for simpler deployments or testing.
+
+```bash
+uv run temporal_agent.py
+```
+
+This file:
+- Defines the workflow
+- Starts the worker
+- Executes the workflow
+- All within the same process using `async with Worker(...)`
+
+**Key difference**: The single-file approach runs both the worker and client in the same process:
+```python
+async with Worker(
+    client,
+    task_queue=running_app.config.temporal.task_queue,
+    workflows=[BasicWorkflow],
+):
+    # Execute workflow while worker is running
+    output = await client.execute_workflow(...)
+```
+
+## Important Configuration Notes
+
+### Execution Engine Setting
+
+The `execution_engine` in `mcp_agent.config.yaml` **MUST** be set to `temporal` for the Temporal plugin to work:
+
+```yaml
+execution_engine: temporal  # Required for Temporal plugin
+```
+
+Without this setting, MCP-Agent will use the default `asyncio` engine and Temporal features won't be available.
+
+### Temporal Configuration
+
+Configure Temporal settings in `mcp_agent.config.yaml`:
+
+```yaml
+temporal:
+  host: "localhost:7233"           # Temporal server address
+  namespace: "default"              # Temporal namespace
+  task_queue: "mcp-agent"          # Task queue name
+  max_concurrent_activities: 10    # Concurrency limit
+  rpc_metadata:
+    X-Client-Name: "mcp-agent"     # Client identification
+```
+
+## File Structure
+
+```
+temporal_plugin/
+├── basic_workflow.py        # Workflow definition
+├── run_worker.py           # Worker process (Method 1)
+├── run_basic_workflow.py   # Workflow client (Method 1)
+├── temporal_agent.py       # Single-file approach (Method 2)
+├── main.py                 # MCP-Agent app setup
+├── mcp_agent.config.yaml   # Configuration (MUST set execution_engine: temporal)
+└── mcp_agent.secrets.yaml  # API keys
+```
+
+## When to Use Each Method
+
+- **Separate Files (Method 1)**: Use when you need:
+  - Distributed workers across multiple machines
+  - Independent scaling of workers and clients
+  - Clear separation of concerns
+  - Production deployments
+
+- **Single File (Method 2)**: Use when you need:
+  - Quick prototyping and testing
+  - Simple deployments
+  - All-in-one execution for demos
+  - Development and debugging
+
+## Troubleshooting
+
+1. **Temporal not working**: Ensure `execution_engine: temporal` in config
+2. **Connection refused**: Start Temporal server with `temporal server start-dev`
+3. **Task queue mismatch**: Verify task queue names match between worker and client
+
+## Further Resources
+
+- [Temporal Documentation](https://docs.temporal.io/)
+- [MCP-Agent Documentation](https://docs.mcp-agent.com/)
+- [MCP-Agent GitHub](https://github.com/lastmile-ai/mcp-agent)

examples/temporal_plugin/basic_workflow.py

@@ -0,0 +1,19 @@
+from temporalio import workflow
+from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM
+from mcp_agent.agents.agent import Agent
+
+
+@workflow.defn
+class BasicWorkflow:
+    @workflow.run
+    async def run(self, prompt: str) -> str:
+        simple_agent = Agent(
+            name="finder",
+            instruction="You are a helpful agent",
+            server_names=["fetch"],
+        )
+
+        async with simple_agent:
+            llm = await simple_agent.attach_llm(OpenAIAugmentedLLM)
+            result = await llm.generate_str(prompt)
+            return result

examples/temporal_plugin/evaluator_optimizer.py

@@ -0,0 +1,115 @@
+import asyncio
+from uuid import uuid4
+from temporalio import workflow
+from mcp_agent.core.context import get_current_context
+from mcp_agent.workflows.evaluator_optimizer.evaluator_optimizer import (
+    EvaluatorOptimizerLLM,
+    QualityRating,
+)
+from mcp_agent.workflows.llm.augmented_llm import RequestParams
+from mcp_agent.workflows.llm.augmented_llm_openai import OpenAIAugmentedLLM
+from mcp_agent.agents.agent import Agent
+from temporalio.client import Client
+from mcp_agent.executor.temporal.plugin import MCPAgentPlugin
+from mcp_agent.app import MCPApp
+from temporalio.worker import Worker
+
+app = MCPApp(name="mcp_basic_agent")
+
+
+@workflow.defn
+class EvaluatorOptimizerWorkflow:
+    @workflow.run
+    async def run(self, prompt: str) -> str:
+        context = get_current_context()
+        logger = context.app.logger
+
+        logger.info("Current config:", data=context.config.model_dump())
+
+        optimizer = Agent(
+            name="optimizer",
+            instruction="""You are a career coach specializing in cover letter writing.
+            You are tasked with generating a compelling cover letter given the job posting,
+            candidate details, and company information. Tailor the response to the company and job requirements.
+            """,
+            server_names=["fetch"],
+        )
+
+        evaluator = Agent(
+            name="evaluator",
+            instruction="""Evaluate the following response based on the criteria below:
+            1. Clarity: Is the language clear, concise, and grammatically correct?
+            2. Specificity: Does the response include relevant and concrete details tailored to the job description?
+            3. Relevance: Does the response align with the prompt and avoid unnecessary information?
+            4. Tone and Style: Is the tone professional and appropriate for the context?
+            5. Persuasiveness: Does the response effectively highlight the candidate's value?
+            6. Grammar and Mechanics: Are there any spelling or grammatical issues?
+            7. Feedback Alignment: Has the response addressed feedback from previous iterations?
+
+            For each criterion:
+            - Provide a rating (EXCELLENT, GOOD, FAIR, or POOR).
+            - Offer specific feedback or suggestions for improvement.
+
+            Summarize your evaluation as a structured response with:
+            - Overall quality rating.
+            - Specific feedback and areas for improvement.""",
+        )
+
+        evaluator_optimizer = EvaluatorOptimizerLLM(
+            optimizer=optimizer,
+            evaluator=evaluator,
+            llm_factory=OpenAIAugmentedLLM,
+            min_rating=QualityRating.EXCELLENT,
+            context=context,
+        )
+
+        result = await evaluator_optimizer.generate_str(
+            message=input,
+            request_params=RequestParams(model="gpt-4o"),
+        )
+
+        return result
+
+
+async def main():
+    async with app.run() as running_app:
+        plugin = MCPAgentPlugin(running_app)
+
+        client = await Client.connect(
+            running_app.config.temporal.host,
+            plugins=[plugin],
+        )
+
+        async with Worker(
+            client,
+            task_queue=running_app.config.temporal.task_queue,
+            workflows=[EvaluatorOptimizerWorkflow],
+        ):
+            job_posting = (
+                "Software Engineer at LastMile AI. Responsibilities include developing AI systems, "
+                "collaborating with cross-functional teams, and enhancing scalability. Skills required: "
+                "Python, distributed systems, and machine learning."
+            )
+            candidate_details = (
+                "Alex Johnson, 3 years in machine learning, contributor to open-source AI projects, "
+                "proficient in Python and TensorFlow. Motivated by building scalable AI systems to solve real-world problems."
+            )
+
+            # This should trigger a 'fetch' call to get the company information
+            company_information = (
+                "Look up from the LastMile AI page: https://lastmileai.dev"
+            )
+
+            task = f"Write a cover letter for the following job posting: {job_posting}\n\nCandidate Details: {candidate_details}\n\nCompany information: {company_information}"
+
+            output = await client.execute_workflow(
+                EvaluatorOptimizerWorkflow.run,
+                task,
+                id=f"basic-workflow-{uuid4()}",
+                task_queue=running_app.config.temporal.task_queue,
+            )
+            print(output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())