Refactor functional tests around reusable agents

Author: Santosh Kumar Radha

tests/functional/README.md

@@ -35,19 +35,29 @@ This test suite runs end-to-end functional tests in an isolated Docker environme
 
 ```
 tests/functional/
+├── agents/                           # Reusable agent definitions
+│   ├── __init__.py
+│   └── quick_start_agent.py
 ├── docker/
 │   ├── docker compose.local.yml      # SQLite mode (fast)
 │   ├── docker compose.postgres.yml   # PostgreSQL mode (production-like)
 │   ├── Dockerfile.test-runner        # Test execution container
 │   ├── agentfield-test.yaml          # Control plane configuration
 │   └── wait-for-services.sh          # Health check script
-├── conftest.py                        # Pytest fixtures
-├── test_hello_world.py                # Example functional test
+├── tests/
+│   ├── test_hello_world.py           # Hello World functional test
+│   └── test_quick_start.py           # README Quick Start validation
+├── utils/
+│   ├── __init__.py
+│   └── agent_server.py               # Shared run-agent helper
+├── conftest.py                       # Pytest fixtures
 ├── requirements.txt                   # Test dependencies
 ├── .env.example                       # Environment template
 └── README.md                          # This file
 ```
 
+The `agents/` directory stores normal-looking AgentField nodes (complete with `if __name__ == "__main__"` hooks) that tests can import and run. Shared helpers such as the `run_agent_server` async context manager live in `utils/` so every test can start/stop agents the same way.
+
 ### Test Flow
 
 1. Docker Compose starts the control plane (and PostgreSQL if needed)
@@ -176,46 +186,39 @@ make test-functional-local
 
 ## 🧪 Writing Tests
 
+### Reusable Agent Nodes
+
+- Put canonical agent implementations in `agents/<name>_agent.py`. Each module should expose a `create_agent(openrouter_config, **kwargs)` helper (see `agents/quick_start_agent.py`).
+- Tests import those helpers, instantiate the agent (exactly like production code), and then spin it up with `utils.agent_server.run_agent_server`.
+- Agent modules can also be executed directly (`python -m agents.quick_start_agent`) because they expose a `create_agent_from_env` helper.
+
 ### Basic Structure
 
 ```python
 import pytest
-from agentfield import Agent
+from agents.my_agent import create_agent
+from utils.agent_server import run_agent_server
 
 @pytest.mark.functional
 @pytest.mark.openrouter
 @pytest.mark.asyncio
 async def test_my_feature(
-    make_test_agent,
-    openrouter_config,  # ALWAYS use this fixture - NEVER hardcode models
+    openrouter_config,
     async_http_client,
 ):
-    # Create agent with OpenRouter config (uses OPENROUTER_MODEL env var)
-    agent = make_test_agent(
-        node_id="my-test-agent",
-        ai_config=openrouter_config,  # This respects OPENROUTER_MODEL
-    )
-    
-    # Define reasoner
-    @agent.reasoner()
-    async def my_reasoner(input_data: str) -> dict:
-        response = await agent.ai(prompt=input_data)
-        return {"result": response}
-    
-    # Start agent and register
-    # ... (see test_hello_world.py for full example)
-    
-    # Execute through control plane
-    result = await async_http_client.post(
-        f"/api/v1/reasoners/{agent.node_id}.my_reasoner",
-        json={"input": {"input_data": "test"}}
-    )
-    
-    # Validate
-    assert result.status_code == 200
-    assert "result" in result.json()
+    agent = create_agent(openrouter_config, node_id="my-test-agent")
+
+    async with run_agent_server(agent):
+        response = await async_http_client.post(
+            f"/api/v1/reasoners/{agent.node_id}.my_reasoner",
+            json={"input": {"input_data": "test"}},
+        )
+        assert response.status_code == 200
+        assert "result" in response.json()
 ```
 
+> `make_test_agent` is still available for quick experiments, but we recommend capturing production-like agents under `agents/` so they can be reused across multiple tests or even run manually.
+
 ### Available Fixtures
 
 #### Configuration Fixtures

tests/functional/agents/__init__.py

@@ -0,0 +1,6 @@
+"""
+Reusable agent definitions for functional tests.
+
+Each module in this package should expose functions that return
+configured `Agent` instances that mirror real deployments.
+"""

tests/functional/agents/quick_start_agent.py

@@ -0,0 +1,100 @@
+"""
+Agent definition that mirrors the README Quick Start example.
+
+Tests can import `create_agent` to obtain a fully configured Agent
+without needing to replicate the agent definition inline.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Dict, Optional
+
+import requests
+from agentfield import AIConfig, Agent
+
+DEFAULT_NODE_ID = "quick-start-agent"
+
+
+def create_agent(
+    ai_config: AIConfig,
+    *,
+    node_id: str = DEFAULT_NODE_ID,
+    callback_url: Optional[str] = None,
+    **agent_kwargs,
+) -> Agent:
+    """
+    Build the Quick Start agent with the canonical fetch_url + summarize flow.
+    """
+    agent_kwargs.setdefault("dev_mode", True)
+    agent_kwargs.setdefault("callback_url", callback_url or "http://test-agent")
+    agent_kwargs.setdefault(
+        "agentfield_server", os.environ.get("AGENTFIELD_SERVER", "http://localhost:8080")
+    )
+
+    agent = Agent(
+        node_id=node_id,
+        ai_config=ai_config,
+        **agent_kwargs,
+    )
+
+    @agent.skill()
+    def fetch_url(url: str) -> str:
+        response = requests.get(url, timeout=10)
+        response.raise_for_status()
+        return response.text
+
+    @agent.reasoner()
+    async def summarize(url: str) -> Dict[str, str]:
+        """
+        Fetch a URL, summarize it via OpenRouter, and return metadata.
+        """
+        content = fetch_url(url)
+        truncated = content[:2000]
+
+        ai_response = await agent.ai(
+            system=(
+                "You summarize documentation for internal verification. "
+                "Be concise and focus on the site's purpose."
+            ),
+            user=(
+                "Summarize the following web page in no more than two sentences. "
+                "Focus on what the site is intended for.\n"
+                f"Content:\n{truncated}"
+            ),
+        )
+        summary_text = getattr(ai_response, "text", str(ai_response)).strip()
+
+        return {
+            "url": url,
+            "summary": summary_text,
+            "content_snippet": truncated[:200],
+        }
+
+    return agent
+
+
+def create_agent_from_env() -> Agent:
+    """
+    Convenience helper to instantiate the agent from environment variables.
+
+    Useful if you want to run this module as a standalone script.
+    """
+    api_key = os.environ["OPENROUTER_API_KEY"]
+    model = os.environ.get("OPENROUTER_MODEL", "openrouter/google/gemini-2.5-flash-lite")
+
+    ai_config = AIConfig(
+        model=model,
+        api_key=api_key,
+        temperature=float(os.environ.get("OPENROUTER_TEMPERATURE", "0.7")),
+        max_tokens=int(os.environ.get("OPENROUTER_MAX_TOKENS", "500")),
+        timeout=float(os.environ.get("OPENROUTER_TIMEOUT", "60.0")),
+        retry_attempts=int(os.environ.get("OPENROUTER_RETRIES", "2")),
+    )
+    return create_agent(ai_config)
+
+
+if __name__ == "__main__":
+    # Allow developers to run: `python -m agents.quick_start_agent`
+    agent = create_agent_from_env()
+    agent.run()