agentpool 2.1.9__py3-none-any.whl

agentpool_config/mcp_server.py

@@ -0,0 +1,243 @@
+"""MCP server configuration."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Annotated, Literal, Self
+
+from pydantic import ConfigDict, Field, HttpUrl
+from schemez import Schema
+
+
+if TYPE_CHECKING:
+    from pydantic_ai.mcp import MCPServer, MCPServerSSE, MCPServerStdio, MCPServerStreamableHTTP
+
+
+class MCPServerAuthSettings(Schema):
+    """Represents authentication configuration for a server.
+
+    Minimal OAuth v2.1 support with sensible defaults.
+    """
+
+    oauth: bool = Field(default=False, title="Enable OAuth")
+
+    # Local callback server configuration
+    redirect_port: int = Field(
+        default=3030, ge=1, lt=65536, examples=[3030, 8080, 9000], title="Redirect port"
+    )
+    redirect_path: str = Field(
+        default="/callback",
+        examples=["/callback", "/auth/callback", "/oauth"],
+        title="Redirect path",
+    )
+
+    # Optional scope override. If set to a list, values are space-joined.
+    scope: str | list[str] | None = Field(
+        default=None,
+        examples=["read write", ["read", "write"], "admin"],
+        title="OAuth scope",
+    )
+
+    # Token persistence: use OS keychain via 'keyring' by default; fallback to 'memory'.
+    persist: Literal["keyring", "memory"] = Field(
+        default="keyring",
+        examples=["keyring", "memory"],
+        title="Token persistence",
+    )
+
+
+class BaseMCPServerConfig(Schema):
+    """Base model for MCP server configuration."""
+
+    type: str = Field(title="Server type")
+    """Type discriminator for MCP server configurations."""
+
+    name: str | None = Field(
+        default=None,
+        examples=["my_server", "api_connector", "file_handler"],
+        title="Server name",
+    )
+    """Optional name for referencing the server."""
+
+    enabled: bool = Field(default=True, title="Server enabled")
+    """Whether this server is currently enabled."""
+
+    env: dict[str, str] | None = Field(default=None, title="Environment variables")
+    """Environment variables to pass to the server process."""
+
+    timeout: float = Field(
+        default=60.0,
+        gt=0,
+        examples=[30.0, 60.0, 120.0],
+        title="Server timeout",
+    )
+    """Timeout for the server process in seconds."""
+
+    def get_env_vars(self) -> dict[str, str]:
+        """Get environment variables for the server process."""
+        env = os.environ.copy()
+        if self.env:
+            env.update(self.env)
+        env["PYTHONIOENCODING"] = "utf-8"
+        return env
+
+    def to_pydantic_ai(self) -> MCPServer:
+        """Convert to pydantic-ai MCP server instance.
+
+        Returns:
+            A pydantic-ai MCP server instance
+        """
+        raise NotImplementedError
+
+    @property
+    def client_id(self) -> str:
+        """Generate a unique client ID for this server configuration."""
+        raise NotImplementedError
+
+    @classmethod
+    def from_string(cls, text: str) -> MCPServerConfig:
+        """Create a MCPServerConfig from a string."""
+        text = text.strip()
+        if text.startswith(("http://", "https://")) and text.endswith("/sse"):
+            return SSEMCPServerConfig(url=HttpUrl(text))
+        if text.startswith(("http://", "https://")):
+            return StreamableHTTPMCPServerConfig(url=HttpUrl(text))
+        return StdioMCPServerConfig.from_string(text)
+
+
+class StdioMCPServerConfig(BaseMCPServerConfig):
+    """MCP server started via stdio.
+
+    Uses subprocess communication through standard input/output streams.
+    """
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "Stdio MCP Server"})
+
+    type: Literal["stdio"] = Field("stdio", init=False)
+    """Stdio server coniguration."""
+
+    command: str = Field(
+        examples=["python", "node", "pipx", "uvx"],
+        title="Command to execute",
+    )
+    """Command to execute (e.g. "pipx", "python", "node")."""
+
+    args: list[str] = Field(
+        default_factory=list,
+        examples=[["run", "mcp-server"], ["-m", "my_mcp_server"], ["--debug"]],
+        title="Command arguments",
+    )
+    """Command arguments (e.g. ["run", "some-server", "--debug"])."""
+
+    @classmethod
+    def from_string(cls, command: str) -> Self:
+        """Create a MCP server from a command string."""
+        parts = command.split(maxsplit=1)
+        cmd = parts[0]
+        args = parts[1].split() if len(parts) > 1 else []
+        return cls(command=cmd, args=args)
+
+    @property
+    def client_id(self) -> str:
+        """Generate a unique client ID for this stdio server configuration."""
+        return f"{self.command}_{' '.join(self.args)}"
+
+    def to_pydantic_ai(self) -> MCPServerStdio:
+        """Convert to pydantic-ai MCPServerStdio instance."""
+        from pydantic_ai.mcp import MCPServerStdio
+
+        return MCPServerStdio(
+            command=self.command,
+            args=self.args,
+            env=self.get_env_vars() if self.env else None,
+            id=self.name,
+            timeout=self.timeout,
+        )
+
+
+class SSEMCPServerConfig(BaseMCPServerConfig):
+    """MCP server using Server-Sent Events transport.
+
+    Connects to a server over HTTP with SSE for real-time communication.
+    """
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "SSE MCP Server"})
+
+    type: Literal["sse"] = Field("sse", init=False)
+    """SSE server configuration."""
+
+    url: HttpUrl = Field(
+        examples=["https://api.example.com/sse", "http://localhost:8080/events"],
+        title="SSE endpoint URL",
+    )
+    """URL of the SSE server endpoint."""
+
+    headers: dict[str, str] | None = Field(default=None, title="HTTP headers")
+    """Headers to send with the SSE request."""
+
+    auth: MCPServerAuthSettings = Field(
+        default_factory=MCPServerAuthSettings,
+        title="Authentication settings",
+    )
+    """OAuth settings for the SSE server."""
+
+    @property
+    def client_id(self) -> str:
+        """Generate a unique client ID for this SSE server configuration."""
+        return f"sse_{self.url}"
+
+    def to_pydantic_ai(self) -> MCPServerSSE:
+        """Convert to pydantic-ai MCPServerSSE instance."""
+        from pydantic_ai.mcp import MCPServerSSE
+
+        url = str(self.url)
+        return MCPServerSSE(url=url, headers=self.headers, id=self.name, timeout=self.timeout)
+
+
+class StreamableHTTPMCPServerConfig(BaseMCPServerConfig):
+    """MCP server using StreamableHttp.
+
+    Connects to a server over HTTP with streamable HTTP.
+    """
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "Streamable HTTP MCP Server"})
+
+    type: Literal["streamable-http"] = Field("streamable-http", init=False)
+    """HTTP server configuration."""
+
+    url: HttpUrl = Field(
+        examples=["https://api.example.com/mcp", "http://localhost:8080/stream"],
+        title="HTTP endpoint URL",
+    )
+    """URL of the HTTP server endpoint."""
+
+    headers: dict[str, str] | None = Field(default=None, title="HTTP headers")
+    """Headers to send with the HTTP request."""
+
+    auth: MCPServerAuthSettings = Field(
+        default_factory=MCPServerAuthSettings,
+        title="Authentication settings",
+    )
+    """OAuth settings for the HTTP server."""
+
+    @property
+    def client_id(self) -> str:
+        """Generate a unique client ID for this streamable HTTP server configuration."""
+        return f"streamable_http_{self.url}"
+
+    def to_pydantic_ai(self) -> MCPServerStreamableHTTP:
+        """Convert to pydantic-ai MCPServerStreamableHTTP instance."""
+        from pydantic_ai.mcp import MCPServerStreamableHTTP
+
+        return MCPServerStreamableHTTP(
+            url=str(self.url),
+            headers=self.headers,
+            id=self.name,
+            timeout=self.timeout,
+        )
+
+
+MCPServerConfig = Annotated[
+    StdioMCPServerConfig | SSEMCPServerConfig | StreamableHTTPMCPServerConfig,
+    Field(discriminator="type"),
+]

agentpool_config/nodes.py

@@ -0,0 +1,202 @@
+"""Team configuration models."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from evented.configs import EventConfig
+from pydantic import ConfigDict, Field, ImportString
+from schemez import Schema
+
+from agentpool_config.event_handlers import EventHandlerConfig
+from agentpool_config.forward_targets import ForwardingTarget
+from agentpool_config.mcp_server import (
+    BaseMCPServerConfig,
+    MCPServerConfig,
+    StdioMCPServerConfig,
+)
+
+
+if TYPE_CHECKING:
+    from agentpool.common_types import IndividualEventHandler
+
+
+ToolConfirmationMode = Literal["always", "never", "per_tool"]
+"""Controls how permission requests are handled:
+
+- "always": Always prompt user for confirmation
+- "never": Auto-grant all permissions (no prompts)
+- "per_tool": Use individual tool settings (treated as "always" for ACP)
+"""
+
+
+class NodeConfig(Schema):
+    """Configuration for a Node of the messaging system."""
+
+    model_config = ConfigDict(
+        frozen=True,
+        arbitrary_types_allowed=True,
+        json_schema_extra={
+            "x-icon": "octicon:workflow-16",
+            "x-doc-title": "Node Configuration",
+        },
+    )
+
+    name: str | None = Field(default=None)
+    """Identifier for the node. Set from dict key, not from YAML."""
+
+    config_file_path: str | None = Field(
+        default=None,
+        exclude=True,
+        examples=["/path/to/config.yml", "configs/agent.yaml"],
+        title="Configuration file path",
+    )
+    """Config file path for resolving relative paths."""
+
+    display_name: str | None = Field(
+        default=None,
+        examples=["Main Agent", "Web Searcher", "Code Assistant"],
+        title="Display name",
+    )
+    """Human-readable display name for the node."""
+
+    description: str | None = Field(
+        default=None,
+        examples=["Main conversation agent", "Handles web search requests"],
+        title="Node description",
+    )
+    """Optional description of the agent / team."""
+
+    triggers: list[EventConfig] = Field(
+        default_factory=list,
+        examples=[
+            [
+                {
+                    "type": "time",
+                    "name": "daily_check",
+                    "schedule": "0 9 * * *",
+                    "prompt": "Daily status update",
+                }
+            ],
+            [
+                {
+                    "type": "file",
+                    "name": "code_watcher",
+                    "paths": ["./src"],
+                    "extensions": [".py"],
+                }
+            ],
+        ],
+        title="Event triggers",
+    )
+    """Event sources that activate this agent / team"""
+
+    connections: list[ForwardingTarget] = Field(
+        default_factory=list,
+        examples=[
+            [
+                {
+                    "type": "node",
+                    "name": "output_agent",
+                    "connection_type": "run",
+                    "wait_for_completion": True,
+                }
+            ],
+            [
+                {
+                    "type": "file",
+                    "path": "logs/messages.txt",
+                    "template": "{{ message.content }}",
+                }
+            ],
+        ],
+        title="Message forwarding targets",
+    )
+    """Targets to forward results to."""
+
+    mcp_servers: list[str | MCPServerConfig] = Field(
+        default_factory=list,
+        title="MCP servers",
+        examples=[
+            ["uvx some-server"],
+            [{"type": "streamable-http", "url": "http://mcp.example.com"}],
+        ],
+    )
+    """List of MCP server configurations:
+    - str entries are converted to StdioMCPServerConfig
+    - MCPServerConfig for full server configuration
+    """
+    # Any should be InputProvider, but this leads to circular import
+    input_provider: ImportString[Any] | None = Field(
+        default=None,
+        title="Input provider",
+    )
+    """Provider for human-input-handling."""
+
+    event_handlers: list[EventHandlerConfig] = Field(
+        default_factory=list,
+        title="Event handlers",
+        examples=[
+            [{"type": "builtin", "handler": "simple"}],
+        ],
+    )
+    """Event handlers for processing agent stream events.
+
+    Supports:
+    - builtin: Simple/detailed console output
+    - tts: Text-to-speech synthesis
+    - callback: Custom handler via import path
+    """
+
+    def get_event_handlers(self) -> list[IndividualEventHandler]:
+        """Get resolved event handlers from configuration.
+
+        Returns:
+            List of event handler callables.
+        """
+        from agentpool_config.event_handlers import resolve_handler_configs
+
+        return resolve_handler_configs(self.event_handlers)
+
+    def get_mcp_servers(self) -> list[MCPServerConfig]:
+        """Get processed MCP server configurations.
+
+        Converts string entries to StdioMCPServerConfigs by splitting
+        into command and arguments.
+
+        Returns:
+            List of MCPServerConfig instances
+
+        Raises:
+            ValueError: If string entry is empty
+        """
+        configs: list[MCPServerConfig] = []
+
+        for server in self.mcp_servers:
+            match server:
+                case str():
+                    parts = server.split()
+                    if not parts:
+                        msg = "Empty MCP server command"
+                        raise ValueError(msg)
+
+                    configs.append(StdioMCPServerConfig(command=parts[0], args=parts[1:]))
+                case BaseMCPServerConfig():
+                    configs.append(server)
+
+        return configs
+
+
+class BaseAgentConfig(NodeConfig):
+    """Base configuration for agents."""
+
+    requires_tool_confirmation: ToolConfirmationMode = Field(
+        default="per_tool",
+        examples=["always", "never", "per_tool"],
+        title="Tool confirmation mode",
+    )
+    """How to handle tool confirmation:
+    - "always": Always require confirmation for all tools
+    - "never": Never require confirmation (ignore tool settings)
+    - "per_tool": Use individual tool settings
+    """

agentpool_config/observability.py

@@ -0,0 +1,191 @@
+"""Configuration models for observability providers."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import ConfigDict, Field, PrivateAttr, SecretStr
+from schemez import Schema
+
+
+class BaseObservabilityConfig(Schema):
+    """Base configuration for observability endpoints."""
+
+    type: str = Field(title="Observability provider type")
+    """Observability provider type."""
+
+    enabled: bool = Field(default=True, title="Provider enabled")
+    """Provider enabled state."""
+
+    service_name: str | None = Field(
+        default=None,
+        examples=["agentpool", "my-ai-service", "production-bot"],
+        title="Service name",
+    )
+    environment: str | None = Field(
+        default=None,
+        examples=["production", "staging", "development"],
+        title="Environment",
+    )
+    protocol: Literal["http/protobuf", "grpc", "http/json"] = Field(
+        default="http/protobuf",
+        examples=["http/protobuf", "grpc", "http/json"],
+        title="Protocol",
+    )
+
+
+class LogfireObservabilityConfig(BaseObservabilityConfig):
+    """Configuration for Logfire endpoint."""
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "Logfire"})
+
+    type: Literal["logfire"] = "logfire"
+    """Logfire endpoint type."""
+
+    token: SecretStr | None = Field(default=None, title="Logfire token")
+    """Logfire token."""
+
+    region: Literal["us", "eu"] = Field(default="us", examples=["us", "eu"], title="Region")
+    """Logfire region."""
+
+    # Private - computed from region
+    _endpoint: str = PrivateAttr()
+    _headers: dict[str, str] = PrivateAttr(default_factory=dict)
+
+    def model_post_init(self, __context: Any, /) -> None:
+        """Compute private attributes from user config."""
+        endpoint = (
+            "https://logfire-eu.pydantic.dev"
+            if self.region == "eu"
+            else "https://logfire-us.pydantic.dev"
+        )
+        object.__setattr__(self, "_endpoint", endpoint)
+
+        if self.token:
+            headers = {"Authorization": f"Bearer {self.token.get_secret_value()}"}
+            object.__setattr__(self, "_headers", headers)
+
+
+class LangsmithObservabilityConfig(BaseObservabilityConfig):
+    """Configuration for Langsmith endpoint."""
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "Langsmith"})
+
+    type: Literal["langsmith"] = "langsmith"
+    """Langsmith observability configuration."""
+
+    api_key: SecretStr | None = Field(default=None, title="Langsmith API key")
+    """Langsmith API key."""
+
+    project_name: str | None = Field(
+        default=None,
+        examples=["my-project", "ai-agents", "production"],
+        title="Project name",
+    )
+
+    _endpoint: str = PrivateAttr(default="https://api.smith.langchain.com")
+    _headers: dict[str, str] = PrivateAttr(default_factory=dict)
+
+    def model_post_init(self, __context: Any, /) -> None:
+        """Compute private attributes from user config."""
+        if self.api_key:
+            headers = {"x-api-key": self.api_key.get_secret_value()}
+            object.__setattr__(self, "_headers", headers)
+
+
+class AgentOpsObservabilityConfig(BaseObservabilityConfig):
+    """Configuration for AgentOps endpoint."""
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "AgentOps"})
+
+    type: Literal["agentops"] = "agentops"
+    """AgentOps observability configuration."""
+
+    api_key: SecretStr | None = Field(default=None, title="AgentOps API key")
+    """AgentOps API key."""
+
+    _endpoint: str = PrivateAttr(default="https://api.agentops.ai")
+    _headers: dict[str, str] = PrivateAttr(default_factory=dict)
+
+    def model_post_init(self, __context: Any, /) -> None:
+        """Compute private attributes from user config."""
+        if self.api_key:
+            headers = {"Authorization": f"Bearer {self.api_key.get_secret_value()}"}
+            object.__setattr__(self, "_headers", headers)
+
+
+class ArizePhoenixObservabilityConfig(BaseObservabilityConfig):
+    """Configuration for Arize Phoenix endpoint."""
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "Arize Phoenix"})
+
+    type: Literal["arize"] = "arize"
+    """Arize observability configuration."""
+
+    api_key: SecretStr | None = Field(default=None, title="Arize API key")
+    """Arize API key."""
+
+    space_key: str | None = Field(
+        default=None,
+        examples=["default", "team-space", "production-space"],
+        title="Space key",
+    )
+    """Arize space key."""
+
+    model_id: str | None = Field(
+        default=None,
+        examples=["gpt-4", "claude-3", "my-model"],
+        title="Model ID",
+    )
+    """Arize model ID."""
+
+    _endpoint: str = PrivateAttr(default="https://api.arize.com")
+    _headers: dict[str, str] = PrivateAttr(default_factory=dict)
+
+    def model_post_init(self, __context: Any, /) -> None:
+        """Compute private attributes from user config."""
+        if self.api_key:
+            headers = {"Authorization": f"Bearer {self.api_key.get_secret_value()}"}
+            object.__setattr__(self, "_headers", headers)
+
+
+class CustomObservabilityConfig(BaseObservabilityConfig):
+    """Configuration for custom OTEL endpoint."""
+
+    model_config = ConfigDict(json_schema_extra={"x-doc-title": "Custom OTEL"})
+
+    type: Literal["custom"] = "custom"
+    """Custom OTEL endpoint configuration."""
+
+    endpoint: str = Field(
+        examples=["https://otel.example.com", "http://localhost:4318"],
+        title="OTEL endpoint",
+    )
+    """Custom OTEL endpoint URL."""
+
+    headers: dict[str, str] = Field(default_factory=dict, title="Custom headers")
+    """Custom headers for the OTEL endpoint."""
+
+
+# Union of all provider configs
+ObservabilityProviderConfig = Annotated[
+    LogfireObservabilityConfig
+    | LangsmithObservabilityConfig
+    | AgentOpsObservabilityConfig
+    | ArizePhoenixObservabilityConfig
+    | CustomObservabilityConfig,
+    Field(discriminator="type"),
+]
+
+
+class ObservabilityConfig(Schema):
+    """Global observability configuration - supports single backend only."""
+
+    enabled: bool = Field(default=True, title="Observability enabled")
+    """Whether observability is enabled."""
+
+    provider: ObservabilityProviderConfig | None = Field(
+        default=None,
+        title="Observability provider",
+    )
+    """Single observability provider configuration."""

agentpool_config/output_types.py

@@ -0,0 +1,55 @@
+"""Models for response fields and definitions."""
+
+from __future__ import annotations
+
+from pydantic import Field
+from schemez import Schema, SchemaDef
+
+
+class StructuredResponseConfig(Schema):
+    """Base class for response definitions.
+
+    Docs: https://phil65.github.io/agentpool/YAML%20Configuration/response_configuration/
+    """
+
+    response_schema: SchemaDef = Field(
+        examples=[
+            {
+                "type": "import",
+                "import_path": "pydantic_ai:BinaryImage",
+            },
+            {
+                "type": "inline",
+                "fields": {
+                    "name": {"type": "str", "description": "User name"},
+                    "age": {"type": "int", "description": "User age"},
+                },
+            },
+        ],
+        title="Response schema",
+    )
+    """A model describing the response schema."""
+
+    description: str | None = Field(
+        default=None,
+        examples=["User profile data", "Search results", "Code analysis output"],
+        title="Response description",
+    )
+    """A description for this response definition."""
+
+    result_tool_name: str = Field(
+        default="final_result",
+        examples=["final_result", "submit_answer", "return_data"],
+        title="Result tool name",
+    )
+    """The tool name for the Agent tool to create the structured response."""
+
+    result_tool_description: str | None = Field(
+        default=None,
+        examples=["Submit the final result", "Return structured data"],
+        title="Result tool description",
+    )
+    """The tool description for the Agent tool to create the structured response."""
+
+    output_retries: int | None = Field(default=None, examples=[1, 3, 5], title="Output retries")
+    """Retry override. How often the Agent should try to validate the response."""