hud-python 0.5.1__py3-none-any.whl → 0.5.13__py3-none-any.whl

hud/__init__.py

@@ -18,7 +18,7 @@ from .telemetry.instrument import instrument
 def trace(*args: object, **kwargs: object) -> EvalContext:
     """Deprecated: Use hud.eval() instead.
 
-    .. deprecated:: 0.5.1
+    .. deprecated:: 0.5.2
         hud.trace() is deprecated. Use hud.eval() or env.eval() instead.
     """
     warnings.warn(

hud/agents/__init__.py

@@ -1,19 +1,78 @@
 from __future__ import annotations
 
+from typing import Any
+
 from .base import MCPAgent
 from .openai import OpenAIAgent
 from .openai_chat import OpenAIChatAgent
 from .operator import OperatorAgent
 
-# Note: These agents are not exported here to avoid requiring optional dependencies.
-# Import directly if needed:
-#   from hud.agents.claude import ClaudeAgent  # requires anthropic
-#   from hud.agents.gemini import GeminiAgent  # requires google-genai
-#   from hud.agents.gemini_cua import GeminiCUAAgent  # requires google-genai
-
 __all__ = [
     "MCPAgent",
     "OpenAIAgent",
     "OpenAIChatAgent",
     "OperatorAgent",
+    "create_agent",
 ]
+
+
+def create_agent(model: str, **kwargs: Any) -> MCPAgent:
+    """Create an agent for a gateway model.
+
+    This routes ALL requests through the HUD gateway. For direct API access
+    (using your own API keys), use the agent classes directly.
+
+    Args:
+        model: Model name (e.g., "gpt-4o", "claude-sonnet-4-5").
+        **kwargs: Additional params passed to agent.create().
+
+    Returns:
+        Configured MCPAgent instance with gateway routing.
+
+    Example:
+        ```python
+        # Gateway routing (recommended)
+        agent = create_agent("gpt-4o")
+        agent = create_agent("claude-sonnet-4-5", temperature=0.7)
+
+        # Direct API access (use agent classes)
+        from hud.agents.claude import ClaudeAgent
+
+        agent = ClaudeAgent.create(model="claude-sonnet-4-5")
+        ```
+    """
+    from hud.agents.gateway import build_gateway_client
+    from hud.agents.resolver import resolve_cls
+
+    # Resolve class and gateway info
+    agent_cls, gateway_info = resolve_cls(model)
+
+    # Get model ID from gateway info or use input
+    model_id = model
+    if gateway_info:
+        model_id = gateway_info.get("model") or gateway_info.get("id") or model
+
+    # Determine provider: from gateway info, or infer from agent class
+    if gateway_info:
+        provider = gateway_info.get("provider") or "openai"
+    else:
+        provider = "openai"
+        if agent_cls.__name__ == "ClaudeAgent":
+            provider = "anthropic"
+        elif agent_cls.__name__ in ("GeminiAgent", "GeminiCUAAgent"):
+            provider = "gemini"
+
+    client = build_gateway_client(provider)
+
+    # Set up kwargs
+    kwargs.setdefault("model", model_id)
+
+    # Use correct client key based on agent type
+    if agent_cls == OpenAIChatAgent:
+        kwargs.setdefault("openai_client", client)
+    else:
+        # Claude and other agents use model_client and validate_api_key
+        kwargs.setdefault("model_client", client)
+        kwargs.setdefault("validate_api_key", False)
+
+    return agent_cls.create(**kwargs)

hud/agents/base.py

@@ -9,11 +9,12 @@ from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any, ClassVar, Literal
 
 import mcp.types as types
-from pydantic import BaseModel, ConfigDict
 
 from hud.types import AgentResponse, BaseAgentConfig, MCPToolCall, MCPToolResult, Trace
 from hud.utils.hud_console import HUDConsole
 
+from .types import BaseCreateParams
+
 if TYPE_CHECKING:
     from hud.environment import Environment
     from hud.eval.context import EvalContext
@@ -22,18 +23,6 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-class BaseCreateParams(BaseModel):
-    """Runtime parameters for agent creation."""
-
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    # Primary way to bind agent to execution context (v5)
-    ctx: Any | None = None  # EvalContext or Environment - agent uses this for tool calls
-
-    auto_respond: bool = False
-    verbose: bool = False
-
-
 class MCPAgent(ABC):
     """
     Base class for MCP-enabled agents.
@@ -208,7 +197,21 @@ class MCPAgent(ABC):
             await self._initialize_from_ctx(ctx)
 
         try:
-            result = await self._run_context(text_to_blocks(ctx.prompt), max_steps=max_steps)
+            # Build initial context - optionally append setup tool output
+            # Check ctx first (task-level override), then fall back to agent config
+            append_setup = getattr(ctx, "append_setup_output", False) or getattr(
+                self.config, "append_setup_output", False
+            )
+            initial_prompt = ctx.prompt
+            if append_setup:
+                setup_output = getattr(ctx, "setup_output", None)
+                if setup_output:
+                    initial_prompt = f"{initial_prompt}\n\n{setup_output}"
+
+            # Build initial blocks (text prompt + optional screenshot)
+            initial_blocks = text_to_blocks(initial_prompt)
+
+            result = await self._run_context(initial_blocks, max_steps=max_steps)
 
             # Propagate error state to context for platform visibility
             if result.isError and hasattr(ctx, "error"):
@@ -342,8 +345,17 @@ class MCPAgent(ABC):
             is_error = False
 
         # Ensure all parameters are the correct type
+        # Use ctx.reward if already set (e.g., from scenario evaluate), otherwise 0.0
+        # Note: For v4 tasks with evaluate_tool, reward is set in __aexit__ after this returns,
+        # so callers should prefer ctx.reward over Trace.reward for the final result.
+        reward = 0.0
+        if self.ctx is not None:
+            ctx_reward = getattr(self.ctx, "reward", None)
+            if ctx_reward is not None:
+                reward = ctx_reward
+
         trace_params = {
-            "reward": 0.0,
+            "reward": reward,
             "done": True,
             "messages": messages,
             "content": final_response.content if final_response else error,
@@ -519,8 +531,14 @@ def find_reward(result: MCPToolResult) -> float:
 
     Agent accepts "reward", "grade", "score", or weighted subscores
 
+    If isError is True, return 0.0 (error results should not contribute positive reward).
     If not found, return 0.0
     """
+    # Error results should return 0.0 - don't extract reward from error responses
+    if result.isError:
+        logger.warning("Evaluate tool returned error, using reward=0.0")
+        return 0.0
+
     accept_keys = ["reward", "grade", "score"]
 
     # Check for direct reward/grade/score keys

hud/agents/claude.py

@@ -5,16 +5,18 @@ from __future__ import annotations
 import copy
 import logging
 from inspect import cleandoc
-from typing import Any, ClassVar, Literal, cast
+from typing import TYPE_CHECKING, Any, ClassVar, Literal, cast
 
 import mcp.types as types
 from anthropic import AsyncAnthropic, AsyncAnthropicBedrock, Omit
 from anthropic.types import CacheControlEphemeralParam
 from anthropic.types.beta import (
     BetaBase64ImageSourceParam,
+    BetaBase64PDFSourceParam,
     BetaContentBlockParam,
     BetaImageBlockParam,
     BetaMessageParam,
+    BetaRequestDocumentBlockParam,
     BetaTextBlockParam,
     BetaToolBash20250124Param,
     BetaToolComputerUse20250124Param,
@@ -23,7 +25,6 @@ from anthropic.types.beta import (
     BetaToolTextEditor20250728Param,
     BetaToolUnionParam,
 )
-from pydantic import ConfigDict
 
 from hud.settings import settings
 from hud.tools.computer.settings import computer_settings
@@ -31,24 +32,13 @@ from hud.types import AgentResponse, BaseAgentConfig, MCPToolCall, MCPToolResult
 from hud.utils.hud_console import HUDConsole
 from hud.utils.types import with_signature
 
-from .base import BaseCreateParams, MCPAgent
-
-logger = logging.getLogger(__name__)
-
-
-class ClaudeConfig(BaseAgentConfig):
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    model_name: str = "Claude"
-    model: str = "claude-sonnet-4-5"
-    model_client: AsyncAnthropic | AsyncAnthropicBedrock | None = None
-    max_tokens: int = 16384
-    use_computer_beta: bool = True
-    validate_api_key: bool = True
+from .base import MCPAgent
+from .types import ClaudeConfig, ClaudeCreateParams
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
 
-class ClaudeCreateParams(BaseCreateParams, ClaudeConfig):
-    pass
+logger = logging.getLogger(__name__)
 
 
 class ClaudeAgent(MCPAgent):
@@ -76,12 +66,20 @@ class ClaudeAgent(MCPAgent):
 
         model_client = self.config.model_client
         if model_client is None:
-            api_key = settings.anthropic_api_key
-            if not api_key:
-                raise ValueError("Anthropic API key not found. Set ANTHROPIC_API_KEY.")
-            model_client = AsyncAnthropic(api_key=api_key)
+            # Default to HUD gateway when HUD_API_KEY is available
+            if settings.api_key:
+                from hud.agents.gateway import build_gateway_client
 
-        self.anthropic_client = model_client
+                model_client = build_gateway_client("anthropic")
+            elif settings.anthropic_api_key:
+                model_client = AsyncAnthropic(api_key=settings.anthropic_api_key)
+            else:
+                raise ValueError(
+                    "No API key found. Set HUD_API_KEY for HUD gateway, "
+                    "or ANTHROPIC_API_KEY for direct Anthropic access."
+                )
+
+        self.anthropic_client: AsyncAnthropic | AsyncAnthropicBedrock = model_client
         self.max_tokens = self.config.max_tokens
         self.use_computer_beta = self.config.use_computer_beta
         self.hud_console = HUDConsole(logger=logger)
@@ -212,7 +210,10 @@ class ClaudeAgent(MCPAgent):
     async def format_tool_results(
         self, tool_calls: list[MCPToolCall], tool_results: list[MCPToolResult]
     ) -> list[BetaMessageParam]:
-        """Format tool results into Claude messages."""
+        """Format tool results into Claude messages.
+
+        Handles EmbeddedResource (PDFs), images, and text content.
+        """
         # Process each tool result
         user_content = []
 
@@ -224,7 +225,9 @@ class ClaudeAgent(MCPAgent):
                 continue
 
             # Convert MCP tool results to Claude format
-            claude_blocks = []
+            claude_blocks: list[
+                BetaTextBlockParam | BetaImageBlockParam | BetaRequestDocumentBlockParam
+            ] = []
 
             if result.isError:
                 # Extract error message from content
@@ -241,6 +244,16 @@ class ClaudeAgent(MCPAgent):
                         claude_blocks.append(text_to_content_block(content.text))
                     elif isinstance(content, types.ImageContent):
                         claude_blocks.append(base64_to_content_block(content.data))
+                    elif isinstance(content, types.EmbeddedResource):
+                        # Handle embedded resources (PDFs)
+                        resource = content.resource
+                        if (
+                            isinstance(resource, types.BlobResourceContents)
+                            and resource.mimeType == "application/pdf"
+                        ):
+                            claude_blocks.append(
+                                document_to_content_block(base64_data=resource.blob)
+                            )
 
             # Add tool result
             user_content.append(tool_use_content_block(tool_use_id, claude_blocks))
@@ -295,7 +308,7 @@ class ClaudeAgent(MCPAgent):
                         display_width_px=computer_settings.ANTHROPIC_COMPUTER_WIDTH,
                         display_height_px=computer_settings.ANTHROPIC_COMPUTER_HEIGHT,
                     )
-                elif tool.name == "computer":
+                elif tool.name == "computer" or tool.name.endswith("_computer"):
                     logger.warning(
                         "Renamed tool %s to 'computer', dropping original 'computer' tool",
                         selected_computer_tool.name,
@@ -322,11 +335,14 @@ class ClaudeAgent(MCPAgent):
         self.claude_tools = []
         for tool in available_tools:
             claude_tool = to_api_tool(tool)
-            if claude_tool is None or "name" not in claude_tool:
+            if claude_tool is None:
                 continue
-            if claude_tool["name"] == "computer":
+            tool_name = claude_tool.get("name")
+            if tool_name is None:
+                continue
+            if tool_name == "computer":
                 self.has_computer_tool = True
-            self.tool_mapping[claude_tool["name"]] = tool.name
+            self.tool_mapping[tool_name] = tool.name
             self.claude_tools.append(claude_tool)
 
     def _add_prompt_caching(self, messages: list[BetaMessageParam]) -> list[BetaMessageParam]:
@@ -372,8 +388,21 @@ def text_to_content_block(text: str) -> BetaTextBlockParam:
     return {"type": "text", "text": text}
 
 
+def document_to_content_block(base64_data: str) -> BetaRequestDocumentBlockParam:
+    """Convert base64 PDF to Claude document content block."""
+    return BetaRequestDocumentBlockParam(
+        type="document",
+        source=BetaBase64PDFSourceParam(
+            type="base64",
+            media_type="application/pdf",
+            data=base64_data,
+        ),
+    )
+
+
 def tool_use_content_block(
-    tool_use_id: str, content: list[BetaTextBlockParam | BetaImageBlockParam]
+    tool_use_id: str,
+    content: Sequence[BetaTextBlockParam | BetaImageBlockParam | BetaRequestDocumentBlockParam],
 ) -> BetaToolResultBlockParam:
     """Create tool result content block."""
-    return {"type": "tool_result", "tool_use_id": tool_use_id, "content": content}
+    return {"type": "tool_result", "tool_use_id": tool_use_id, "content": content}  # pyright: ignore[reportReturnType]

hud/agents/gateway.py

@@ -0,0 +1,42 @@
+"""Gateway client utilities for HUD inference gateway."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_gateway_client(provider: str) -> Any:
+    """Build a client configured for HUD gateway routing.
+
+    Args:
+        provider: Provider name ("anthropic", "openai", "gemini", etc.)
+
+    Returns:
+        Configured async client for the provider.
+    """
+    from hud.settings import settings
+
+    provider = provider.lower()
+
+    if provider == "anthropic":
+        from anthropic import AsyncAnthropic
+
+        return AsyncAnthropic(api_key=settings.api_key, base_url=settings.hud_gateway_url)
+
+    if provider == "gemini":
+        from google import genai
+        from google.genai.types import HttpOptions
+
+        return genai.Client(
+            api_key="PLACEHOLDER",
+            http_options=HttpOptions(
+                api_version="v1beta",
+                base_url=settings.hud_gateway_url,
+                headers={"Authorization": f"Bearer {settings.api_key}"},
+            ),
+        )
+
+    # OpenAI-compatible (openai, azure, together, groq, fireworks, etc.)
+    from openai import AsyncOpenAI
+
+    return AsyncOpenAI(api_key=settings.api_key, base_url=settings.hud_gateway_url)

hud/agents/gemini.py

@@ -8,37 +8,18 @@ from typing import Any, ClassVar, cast
 import mcp.types as types
 from google import genai
 from google.genai import types as genai_types
-from pydantic import ConfigDict
 
 from hud.settings import settings
 from hud.types import AgentResponse, BaseAgentConfig, MCPToolCall, MCPToolResult
 from hud.utils.hud_console import HUDConsole
 from hud.utils.types import with_signature
 
-from .base import BaseCreateParams, MCPAgent
+from .base import MCPAgent
+from .types import GeminiConfig, GeminiCreateParams
 
 logger = logging.getLogger(__name__)
 
 
-class GeminiConfig(BaseAgentConfig):
-    """Configuration for `GeminiAgent`."""
-
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    model_name: str = "Gemini"
-    model: str = "gemini-3-pro-preview"
-    model_client: genai.Client | None = None
-    temperature: float = 1.0
-    top_p: float = 0.95
-    top_k: int = 40
-    max_output_tokens: int = 8192
-    validate_api_key: bool = True
-
-
-class GeminiCreateParams(BaseCreateParams, GeminiConfig):
-    pass
-
-
 class GeminiAgent(MCPAgent):
     """
     Gemini agent that uses MCP servers for tool execution.
@@ -61,10 +42,18 @@ class GeminiAgent(MCPAgent):
 
         model_client = self.config.model_client
         if model_client is None:
-            api_key = settings.gemini_api_key
-            if not api_key:
-                raise ValueError("Gemini API key not found. Set GEMINI_API_KEY.")
-            model_client = genai.Client(api_key=api_key)
+            # Default to HUD gateway when HUD_API_KEY is available
+            if settings.api_key:
+                from hud.agents.gateway import build_gateway_client
+
+                model_client = build_gateway_client("gemini")
+            elif settings.gemini_api_key:
+                model_client = genai.Client(api_key=settings.gemini_api_key)
+            else:
+                raise ValueError(
+                    "No API key found. Set HUD_API_KEY for HUD gateway, "
+                    "or GEMINI_API_KEY for direct Gemini access."
+                )
 
         if self.config.validate_api_key:
             try:
@@ -72,7 +61,7 @@ class GeminiAgent(MCPAgent):
             except Exception as e:
                 raise ValueError(f"Gemini API key is invalid: {e}") from e
 
-        self.gemini_client = model_client
+        self.gemini_client: genai.Client = model_client
         self.temperature = self.config.temperature
         self.top_p = self.config.top_p
         self.top_k = self.config.top_k

hud/agents/gemini_cua.py

@@ -7,14 +7,14 @@ from typing import Any, ClassVar
 
 import mcp.types as types
 from google.genai import types as genai_types
-from pydantic import ConfigDict, Field
 
 from hud.tools.computer.settings import computer_settings
 from hud.types import AgentResponse, BaseAgentConfig, MCPToolCall, MCPToolResult
 from hud.utils.types import with_signature
 
-from .base import BaseCreateParams, MCPAgent
-from .gemini import GeminiAgent, GeminiConfig
+from .base import MCPAgent
+from .gemini import GeminiAgent
+from .types import GeminiCUAConfig, GeminiCUACreateParams
 
 logger = logging.getLogger(__name__)
 
@@ -56,20 +56,6 @@ what they asked.
 """.strip()
 
 
-class GeminiCUAConfig(GeminiConfig):
-    """Configuration for `GeminiCUAAgent`."""
-
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    model_name: str = "GeminiCUA"
-    model: str = "gemini-2.5-computer-use-preview-10-2025"
-    excluded_predefined_functions: list[str] = Field(default_factory=list)
-
-
-class GeminiCUACreateParams(BaseCreateParams, GeminiCUAConfig):
-    pass
-
-
 class GeminiCUAAgent(GeminiAgent):
     """
     Gemini Computer Use Agent that extends GeminiAgent with computer use capabilities.
@@ -123,6 +109,9 @@ class GeminiCUAAgent(GeminiAgent):
                 )
             )
 
+        if tool.name == "computer" or tool.name.endswith("_computer"):
+            return None
+
         # For non-computer tools, use the parent implementation
         return super()._to_gemini_tool(tool)
 

hud/agents/misc/response_agent.py

@@ -6,6 +6,7 @@ from typing import Literal
 from openai import AsyncOpenAI
 
 from hud.settings import settings
+from hud.telemetry import instrument
 
 logger = logging.getLogger(__name__)
 
@@ -64,6 +65,11 @@ class ResponseAgent:
         self.model = model
         self.system_prompt = system_prompt or DEFAULT_SYSTEM_PROMPT
 
+    @instrument(
+        category="agent",
+        name="response_agent",
+        internal_type="user-message",
+    )
     async def determine_response(self, agent_message: str) -> ResponseType:
         """
         Determine whether the agent should stop or continue based on its message.
@@ -86,6 +92,7 @@ class ResponseAgent:
                 ],
                 temperature=0.1,
                 max_tokens=5,
+                extra_headers={"Trace-Id": ""},
             )
 
             response_text = response.choices[0].message.content

hud/agents/openai.py

@@ -29,39 +29,18 @@ from openai.types.responses import (
 from openai.types.responses.response_create_params import ToolChoice  # noqa: TC002
 from openai.types.responses.response_input_param import FunctionCallOutput, Message
 from openai.types.shared_params.reasoning import Reasoning  # noqa: TC002
-from pydantic import ConfigDict
 
 from hud.settings import settings
 from hud.types import AgentResponse, BaseAgentConfig, MCPToolCall, MCPToolResult, Trace
 from hud.utils.strict_schema import ensure_strict_json_schema
 from hud.utils.types import with_signature
 
-from .base import BaseCreateParams, MCPAgent
+from .base import MCPAgent
+from .types import OpenAIConfig, OpenAICreateParams
 
 logger = logging.getLogger(__name__)
 
 
-class OpenAIConfig(BaseAgentConfig):
-    """Configuration model for `OpenAIAgent`."""
-
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    model_name: str = "OpenAI"
-    model: str = "gpt-5.1"
-    model_client: AsyncOpenAI | None = None
-    max_output_tokens: int | None = None
-    temperature: float | None = None
-    reasoning: Reasoning | None = None
-    tool_choice: ToolChoice | None = None
-    truncation: Literal["auto", "disabled"] | None = None
-    parallel_tool_calls: bool | None = None
-    validate_api_key: bool = True
-
-
-class OpenAICreateParams(BaseCreateParams, OpenAIConfig):
-    pass
-
-
 class OpenAIAgent(MCPAgent):
     """Generic OpenAI agent that can execute MCP tools through the Responses API."""
 
@@ -79,10 +58,18 @@ class OpenAIAgent(MCPAgent):
 
         model_client = self.config.model_client
         if model_client is None:
-            api_key = settings.openai_api_key
-            if not api_key:
-                raise ValueError("OpenAI API key not found. Set OPENAI_API_KEY.")
-            model_client = AsyncOpenAI(api_key=api_key)
+            # Default to HUD gateway when HUD_API_KEY is available
+            if settings.api_key:
+                from hud.agents.gateway import build_gateway_client
+
+                model_client = build_gateway_client("openai")
+            elif settings.openai_api_key:
+                model_client = AsyncOpenAI(api_key=settings.openai_api_key)
+            else:
+                raise ValueError(
+                    "No API key found. Set HUD_API_KEY for HUD gateway, "
+                    "or OPENAI_API_KEY for direct OpenAI access."
+                )
 
         if self.config.validate_api_key:
             try:
@@ -90,11 +77,11 @@ class OpenAIAgent(MCPAgent):
             except Exception as exc:  # pragma: no cover - network validation
                 raise ValueError(f"OpenAI API key is invalid: {exc}") from exc
 
-        self.openai_client = model_client
+        self.openai_client: AsyncOpenAI = model_client
         self._model = self.config.model
         self.max_output_tokens = self.config.max_output_tokens
         self.temperature = self.config.temperature
-        self.reasoning = self.config.reasoning
+        self.reasoning: Reasoning | None = self.config.reasoning
         self.tool_choice: ToolChoice | None = self.config.tool_choice
         self.parallel_tool_calls = self.config.parallel_tool_calls
         self.truncation: Literal["auto", "disabled"] | None = self.config.truncation

hud/agents/openai_chat.py

@@ -22,14 +22,14 @@ from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 import mcp.types as types
 from openai import AsyncOpenAI
-from pydantic import ConfigDict, Field
 
 from hud.settings import settings
 from hud.types import AgentResponse, BaseAgentConfig, MCPToolCall, MCPToolResult
 from hud.utils.hud_console import HUDConsole
 from hud.utils.types import with_signature
 
-from .base import BaseCreateParams, MCPAgent
+from .base import MCPAgent
+from .types import OpenAIChatConfig, OpenAIChatCreateParams
 
 if TYPE_CHECKING:
     from openai.types.chat import ChatCompletionToolParam
@@ -38,23 +38,6 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-class OpenAIChatConfig(BaseAgentConfig):
-    """Configuration for `OpenAIChatAgent`."""
-
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-
-    model_name: str = "OpenAI Chat"
-    model: str = "gpt-5-mini"
-    openai_client: AsyncOpenAI | None = None
-    api_key: str | None = None
-    base_url: str | None = None
-    completion_kwargs: dict[str, Any] = Field(default_factory=dict)
-
-
-class OpenAIChatCreateParams(BaseCreateParams, OpenAIChatConfig):
-    pass
-
-
 class OpenAIChatAgent(MCPAgent):
     """MCP-enabled agent that speaks the OpenAI *chat.completions* protocol."""
 
@@ -82,6 +65,7 @@ class OpenAIChatAgent(MCPAgent):
                 "Use HUD_API_KEY for gateway auth and BYOK headers for provider keys."
             )
 
+        self.oai: AsyncOpenAI
         if self.config.openai_client is not None:
             self.oai = self.config.openai_client
         elif self.config.api_key is not None or self.config.base_url is not None: