Make Phase and Orchestrator model-agnostic

Author: luisorofino

ddev/src/ddev/ai/agent/build.py

@@ -0,0 +1,77 @@
+# (C) Datadog, Inc. 2026-present
+# All rights reserved
+# Licensed under a 3-clause BSD style license (see LICENSE)
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from ddev.ai.agent.anthropic_client import AnthropicAgent
+from ddev.ai.agent.base import BaseAgent
+from ddev.ai.tools.fs.file_registry import FileRegistry
+from ddev.ai.tools.registry import ToolRegistry
+
+if TYPE_CHECKING:
+    from ddev.ai.phases.config import AgentConfig
+
+AgentBuilder = Callable[[str, str], tuple[BaseAgent[Any], ToolRegistry]]
+
+
+def _resolve_client(agent_clients: dict[str, Any], provider: str) -> Any:
+    client = agent_clients.get(provider)
+    if client is None:
+        raise ValueError(f"No client provided for agent provider {provider!r}")
+    return client
+
+
+def build_agent(
+    agent_config: AgentConfig,
+    agent_clients: dict[str, Any],
+    system_prompt: str,
+    owner_id: str,
+    file_registry: FileRegistry,
+) -> tuple[BaseAgent[Any], ToolRegistry]:
+    """Construct a provider-specific BaseAgent and its ToolRegistry from an AgentConfig."""
+
+    tool_registry = ToolRegistry.from_names(
+        agent_config.tools,
+        owner_id=owner_id,
+        file_registry=file_registry,
+    )
+
+    if agent_config.provider == "anthropic":
+        kwargs: dict[str, Any] = {}
+        if agent_config.model is not None:
+            kwargs["model"] = agent_config.model
+        if agent_config.max_tokens is not None:
+            kwargs["max_tokens"] = agent_config.max_tokens
+        agent: BaseAgent[Any] = AnthropicAgent(
+            client=_resolve_client(agent_clients, "anthropic"),
+            tools=tool_registry,
+            system_prompt=system_prompt,
+            name=owner_id,
+            **kwargs,
+        )
+        return agent, tool_registry
+
+    raise ValueError(f"Unknown agent provider: {agent_config.provider!r}")
+
+
+def make_agent_builder(
+    agent_config: AgentConfig,
+    agent_clients: dict[str, Any],
+    file_registry: FileRegistry,
+) -> AgentBuilder:
+    """Return a closure that builds an agent+registry given a rendered system_prompt and owner_id."""
+
+    def builder(system_prompt: str, owner_id: str) -> tuple[BaseAgent[Any], ToolRegistry]:
+        return build_agent(
+            agent_config=agent_config,
+            agent_clients=agent_clients,
+            system_prompt=system_prompt,
+            owner_id=owner_id,
+            file_registry=file_registry,
+        )
+
+    return builder

ddev/src/ddev/ai/phases/agentic_phase.py

@@ -7,17 +7,15 @@
 from pathlib import Path
 from typing import Any
 
-import anthropic
-
-from ddev.ai.agent.anthropic_client import AnthropicAgent
+from ddev.ai.agent.base import BaseAgent
+from ddev.ai.agent.build import AgentBuilder
 from ddev.ai.callbacks.callbacks import Callbacks
 from ddev.ai.phases.base import Phase, PhaseOutcome
 from ddev.ai.phases.checkpoint import CheckpointManager
 from ddev.ai.phases.config import AgentConfig, CheckpointConfig, FlowConfigError, PhaseConfig, TaskConfig
 from ddev.ai.phases.template import render_inline, render_prompt
 from ddev.ai.react.process import ReActProcess
 from ddev.ai.tools.fs.file_registry import FileRegistry
-from ddev.ai.tools.registry import ToolRegistry
 
 
 def render_task_prompt(
@@ -55,8 +53,7 @@ def __init__(
         phase_id: str,
         dependencies: list[str],
         config: PhaseConfig,
-        agent_config: AgentConfig,
-        anthropic_client: anthropic.AsyncAnthropic,
+        agent_builder: AgentBuilder,
         checkpoint_manager: CheckpointManager,
         runtime_variables: dict[str, str],
         flow_variables: dict[str, str],
@@ -77,8 +74,7 @@ def __init__(
             callbacks=callbacks,
             logger=logger,
         )
-        self._agent_config = agent_config
-        self._anthropic_client = anthropic_client
+        self._agent_builder = agent_builder
 
     @classmethod
     def validate_config(
@@ -124,33 +120,14 @@ async def run_tasks(
             total_output += last_result.total_output_tokens
         return total_input, total_output
 
-    def _build_agent_and_process(self, context: dict[str, Any]) -> tuple[AnthropicAgent, ReActProcess]:
+    def _build_agent_and_process(self, context: dict[str, Any]) -> tuple[BaseAgent[Any], ReActProcess]:
         """Build the agent and ReAct process used to drive task execution."""
         system_prompt = render_prompt(
             self._config_dir / "prompts" / f"{self._config.agent}.md",
             context,
             self._resolver,
         )
-        tool_registry = ToolRegistry.from_names(
-            self._agent_config.tools,
-            owner_id=self._phase_id,
-            file_registry=self._file_registry,
-        )
-
-        agent_kwargs: dict[str, Any] = {}
-        if self._agent_config.model is not None:
-            agent_kwargs["model"] = self._agent_config.model
-        if self._agent_config.max_tokens is not None:
-            agent_kwargs["max_tokens"] = self._agent_config.max_tokens
-
-        agent = AnthropicAgent(
-            client=self._anthropic_client,
-            tools=tool_registry,
-            system_prompt=system_prompt,
-            name=self._phase_id,
-            **agent_kwargs,
-        )
-
+        agent, tool_registry = self._agent_builder(system_prompt, self._phase_id)
         process = ReActProcess(
             agent=agent,
             tool_registry=tool_registry,
@@ -160,7 +137,7 @@ def _build_agent_and_process(self, context: dict[str, Any]) -> tuple[AnthropicAg
 
     async def _run_memory_step(
         self,
-        agent: AnthropicAgent,
+        agent: BaseAgent[Any],
         context: dict[str, Any],
     ) -> tuple[str, int, int]:
         """Run the final summary turn. Returns (memory_text, input_tokens, output_tokens)."""

ddev/src/ddev/ai/phases/base.py

@@ -43,17 +43,6 @@ def get(self, name: str) -> type["Phase"]:
         return self._registry[name]
 
 
-def _make_memory_resolver(checkpoint_manager: CheckpointManager) -> Callable[[str], str]:
-    """Build a resolver that reads phase memory files on demand for template substitution."""
-
-    def resolve(key: str) -> str:
-        if key.endswith("_memory"):
-            return checkpoint_manager.memory_content(key.removesuffix("_memory"))
-        return f"<VARIABLE UNDEFINED: {key}>"
-
-    return resolve
-
-
 class Phase(AsyncProcessor[PhaseTrigger]):
     """Lifecycle base for all phases.
 
@@ -133,7 +122,7 @@ async def process_message(self, message: PhaseTrigger) -> None:
             "phase_name": self._phase_id,
             "checkpoints": self._checkpoint_manager.read(),
         }
-        self._resolver = _make_memory_resolver(self._checkpoint_manager)
+        self._resolver = self._checkpoint_manager.resolve_template_variable
 
         outcome = await self.execute(context)
 

ddev/src/ddev/ai/phases/checkpoint.py

@@ -55,3 +55,9 @@ def memory_content(self, phase_id: str) -> str:
         """Return the contents of a phase's memory file, or a NOT FOUND placeholder."""
         path = self.memory_path(phase_id)
         return path.read_text(encoding="utf-8") if path.exists() else f"<MEMORY NOT FOUND: {phase_id}>"
+
+    def resolve_template_variable(self, key: str) -> str:
+        """Resolve a template variable. ``<phase>_memory`` keys read the matching memory file."""
+        if key.endswith("_memory"):
+            return self.memory_content(key.removesuffix("_memory"))
+        return f"<VARIABLE UNDEFINED: {key}>"

ddev/src/ddev/ai/phases/config.py

@@ -80,6 +80,7 @@ def exactly_one_source(self) -> CheckpointConfig:
 
 class AgentConfig(BaseModel):
     model_config = ConfigDict(extra="forbid")
+    provider: str = "anthropic"
     model: str | None = None
     max_tokens: int | None = None
     tools: list[str] = []

ddev/src/ddev/ai/phases/orchestrator.py

@@ -8,8 +8,7 @@
 from pathlib import Path
 from typing import Any
 
-import anthropic
-
+from ddev.ai.agent.build import make_agent_builder
 from ddev.ai.callbacks.callbacks import Callbacks
 from ddev.ai.phases.agentic_phase import AgenticPhase
 from ddev.ai.phases.base import Phase, PhaseRegistry
@@ -48,22 +47,26 @@ def __init__(
         flow_yaml_path: Path,
         checkpoint_path: Path,
         runtime_variables: dict[str, str],
-        anthropic_client: anthropic.AsyncAnthropic,
+        agent_clients: dict[str, Any],
         file_access_policy: FileAccessPolicy,
         callbacks: Callbacks | None = None,
         grace_period: float = 10,
         logger: logging.Logger | None = None,
     ) -> None:
         """Initialize the orchestrator.
 
+        ``agent_clients`` maps provider name (e.g. ``"anthropic"``) to a constructed
+        provider client. ``build_agent`` looks up the right one based on each
+        ``AgentConfig.provider``.
+
         ``file_access_policy`` must have ``write_root`` set to the integration
         output directory so that agent writes are confined to that path.
         """
         super().__init__(logger=logger or logging.getLogger(__name__), grace_period=grace_period)
         self._flow_yaml_path = flow_yaml_path
         self._checkpoint_path = checkpoint_path
         self._runtime_variables = runtime_variables
-        self._anthropic_client = anthropic_client
+        self._agent_clients = agent_clients
         self._callbacks: Callbacks = callbacks or Callbacks()
         self._phase_registry = PhaseRegistry()
         self._failed_phase: str | None = None
@@ -112,11 +115,13 @@ async def on_initialize(self) -> None:
                 "logger": self._logger,
             }
             if issubclass(phase_cls, AgenticPhase):
-                if phase_config.agent is not None:
-                    phase_kwargs["agent_config"] = config.agents[phase_config.agent]
-                    phase_kwargs["anthropic_client"] = self._anthropic_client
-                else:
+                if phase_config.agent is None:
                     raise FlowConfigError(f"Phase '{phase_id}': agent must be set for AgenticPhase")
+                phase_kwargs["agent_builder"] = make_agent_builder(
+                    agent_config=config.agents[phase_config.agent],
+                    agent_clients=self._agent_clients,
+                    file_registry=self._file_registry,
+                )
 
             phase = phase_cls(**phase_kwargs)
 

ddev/tests/ai/phases/conftest.py

@@ -4,14 +4,13 @@
 
 import asyncio
 from typing import Any
-from unittest.mock import MagicMock
 
 import pytest
 
 from ddev.ai.agent.types import AgentResponse, ContextUsage, StopReason, TokenUsage, ToolResultMessage
 from ddev.ai.phases.agentic_phase import AgenticPhase
 from ddev.ai.phases.checkpoint import CheckpointManager
-from ddev.ai.phases.config import AgentConfig, PhaseConfig, TaskConfig
+from ddev.ai.phases.config import PhaseConfig, TaskConfig
 from ddev.ai.tools.fs.file_access_policy import FileAccessPolicy
 from ddev.ai.tools.fs.file_registry import FileRegistry
 from ddev.ai.tools.registry import ToolRegistry
@@ -86,24 +85,21 @@ async def compact_preserving_last_turn(self) -> AgentResponse | None:
         return None
 
 
-def make_agent_factory(mock_agent: MockAgent, captured_kwargs: dict[str, Any] | None = None):
-    """Create a callable that replaces AnthropicAgent constructor, returning the given mock.
+def make_agent_builder(mock_agent: MockAgent, captured_kwargs: dict[str, Any] | None = None):
+    """Create an agent_builder that returns the given mock and an empty ToolRegistry.
 
-    If ``captured_kwargs`` is provided, every call updates it with the kwargs passed to
-    the constructor — useful for asserting on system_prompt, tools, etc.
+    If ``captured_kwargs`` is provided, every call records the system_prompt and
+    owner_id passed in — useful for asserting on prompt rendering.
     """
 
-    def factory(**kwargs: Any) -> MockAgent:
+    def builder(system_prompt: str, owner_id: str) -> tuple[MockAgent, ToolRegistry]:
         if captured_kwargs is not None:
-            captured_kwargs.update(kwargs)
-        mock_agent.name = kwargs.get("name", "mock")
-        return mock_agent
+            captured_kwargs["system_prompt"] = system_prompt
+            captured_kwargs["owner_id"] = owner_id
+        mock_agent.name = owner_id
+        return mock_agent, ToolRegistry([])
 
-    return factory
-
-
-def _empty_registry_from_names(cls, names, *, owner_id, file_registry):
-    return ToolRegistry([])
+    return builder
 
 
 def make_agent_phase(
@@ -116,7 +112,6 @@ def make_agent_phase(
     dependencies: list[str] | None = None,
     tasks: list[TaskConfig] | None = None,
     checkpoint=None,
-    agent_tools: list[str] | None = None,
     flow_variables: dict[str, str] | None = None,
     runtime_variables: dict[str, str] | None = None,
     context_compact_threshold_pct: int = 80,
@@ -125,31 +120,22 @@ def make_agent_phase(
 ) -> tuple[AgenticPhase, CheckpointManager]:
     """Build an AgenticPhase ready for process_message-driven tests.
 
-    Patches ``AnthropicAgent`` and ``ToolRegistry.from_names`` so no real LLM or tools
-    are constructed. Pass ``captured_agent_kwargs`` (a dict) to record AnthropicAgent
-    constructor kwargs across calls (e.g. to inspect system_prompt rendering).
+    Injects a mock agent_builder so no real LLM or tools are constructed. Pass
+    ``captured_agent_kwargs`` (a dict) to record the rendered system_prompt and owner_id.
     """
-    monkeypatch.setattr(
-        "ddev.ai.phases.agentic_phase.AnthropicAgent",
-        make_agent_factory(mock_agent, captured_agent_kwargs),
-    )
-    monkeypatch.setattr(ToolRegistry, "from_names", classmethod(_empty_registry_from_names))
-
     config = PhaseConfig(
         agent="writer",
         tasks=tasks or [TaskConfig(name="t1", prompt="Do the work.")],
         checkpoint=checkpoint,
         context_compact_threshold_pct=context_compact_threshold_pct,
     )
-    agent_config = AgentConfig(tools=agent_tools or [])
     checkpoint_manager = CheckpointManager(flow_dir / "checkpoints.yaml")
 
     phase = AgenticPhase(
         phase_id=phase_id,
         dependencies=dependencies or [],
         config=config,
-        agent_config=agent_config,
-        anthropic_client=MagicMock(),
+        agent_builder=make_agent_builder(mock_agent, captured_agent_kwargs),
         checkpoint_manager=checkpoint_manager,
         runtime_variables=runtime_variables or {},
         flow_variables=flow_variables or {},