agentpool 2.1.9__py3-none-any.whl

agentpool/testing.py

@@ -0,0 +1,129 @@
+"""Testing utilities for end-to-end ACP testing.
+
+This module provides a lightweight test harness for running end-to-end tests
+against the agentpool ACP server. It uses ACPAgent as the client, connecting
+to a agentpool serve-acp subprocess.
+
+Example:
+    ```python
+    async def test_basic_prompt():
+        async with acp_test_session("tests/fixtures/simple.yml") as agent:
+            result = await agent.run("Say hello")
+            assert result.content
+
+    async def test_filesystem_tool():
+        async with acp_test_session(
+            "tests/fixtures/with_tools.yml",
+            file_access=True,
+            terminal_access=True,
+        ) as agent:
+            result = await agent.run("List files in the current directory")
+            assert "pyproject.toml" in result.content
+    ```
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Sequence
+
+    from evented.configs import EventConfig
+
+    from agentpool.agents.acp_agent import ACPAgent
+    from agentpool.common_types import BuiltinEventHandlerType, IndividualEventHandler
+
+
+@asynccontextmanager
+async def acp_test_session(
+    config: str | Path | None = None,
+    *,
+    file_access: bool = True,
+    terminal_access: bool = True,
+    providers: list[str] | None = None,
+    debug_messages: bool = False,
+    debug_file: str | None = None,
+    debug_commands: bool = False,
+    agent: str | None = None,
+    load_skills: bool = False,
+    cwd: str | Path | None = None,
+    event_configs: Sequence[EventConfig] | None = None,
+    event_handlers: Sequence[IndividualEventHandler | BuiltinEventHandlerType] | None = None,
+) -> AsyncIterator[ACPAgent[Any]]:
+    """Create an end-to-end ACP test session using agentpool as server.
+
+    This context manager starts an ACPAgent connected to a agentpool serve-acp
+    subprocess, enabling full round-trip testing of the ACP protocol.
+
+    Args:
+        config: Path to agent configuration YAML file. If None, uses default config.
+        file_access: Enable file system access for agents.
+        terminal_access: Enable terminal access for agents.
+        providers: Model providers to search for models.
+        debug_messages: Save raw JSON-RPC messages to debug file.
+        debug_file: File path for JSON-RPC debug messages.
+        debug_commands: Enable debug slash commands for testing.
+        agent: Name of specific agent to use from config.
+        load_skills: Load client-side skills from .claude/skills directory.
+        cwd: Working directory for the ACP server subprocess.
+        event_configs: Event configurations for the agent.
+        event_handlers: Event handlers for the agent (e.g., ["detailed"] for logging).
+
+    Yields:
+        ACPAgent instance connected to the test server.
+
+    Example:
+        ```python
+        async def test_echo():
+            async with acp_test_session("my_config.yml") as agent:
+                result = await agent.run("Hello!")
+                assert "Hello" in result.content
+        ```
+    """
+    from agentpool.agents.acp_agent import ACPAgent
+
+    # Build command line arguments
+    args = ["run", "agentpool", "serve-acp"]
+
+    if config is not None:
+        args.extend(["--config", str(config)])
+
+    if not file_access:
+        args.append("--no-file-access")
+
+    if not terminal_access:
+        args.append("--no-terminal-access")
+
+    if providers:
+        for provider in providers:
+            args.extend(["--model-provider", provider])
+
+    if debug_messages:
+        args.append("--debug-messages")
+
+    if debug_file:
+        args.extend(["--debug-file", debug_file])
+
+    if debug_commands:
+        args.append("--debug-commands")
+
+    if agent:
+        args.extend(["--agent", agent])
+
+    if not load_skills:
+        args.append("--no-skills")
+
+    working_dir = str(cwd) if cwd else str(Path.cwd())
+
+    async with ACPAgent(
+        command="uv",
+        args=args,
+        cwd=working_dir,
+        event_configs=event_configs,
+        event_handlers=event_handlers,
+    ) as acp_agent:
+        yield acp_agent

agentpool/text_templates/__init__.py

@@ -0,0 +1,39 @@
+"""Package resources for AgentPool configuration."""
+
+from __future__ import annotations
+
+import importlib.resources
+from functools import cache
+from typing import Final, Literal
+
+_RESOURCES = importlib.resources.files("agentpool.text_templates")
+
+DEFAULT_SYSTEM_PROMPT: Final[str] = str(_RESOURCES / "system_prompt.jinja")
+"""Path to the default system prompt template."""
+
+FormatStyle = Literal["simple", "detailed", "markdown"]
+
+
+@cache
+def get_system_prompt() -> str:
+    """Get the default system prompt template content."""
+    return (_RESOURCES / "system_prompt.jinja").read_text()
+
+
+@cache
+def get_tool_call_template(style: FormatStyle) -> str:
+    """Get tool call template by style."""
+    files = {
+        "simple": "tool_call_simple.jinja",
+        "detailed": "tool_call_default.jinja",
+        "markdown": "tool_call_markdown.jinja",
+    }
+    return (_RESOURCES / files[style]).read_text()
+
+
+__all__ = [
+    "DEFAULT_SYSTEM_PROMPT",
+    "FormatStyle",
+    "get_system_prompt",
+    "get_tool_call_template",
+]

agentpool/text_templates/system_prompt.jinja

@@ -0,0 +1,30 @@
+{%- if inject_agent_info and agent.name %}You are {{ agent.name }}{% if agent.description %}. {{ agent.description }}{% endif %}.
+
+{% endif -%}
+{%- if inject_tools != "off" -%}
+{%- set tools = agent.tools.get_tools("enabled") -%}
+{%- if tools %}
+
+{%- if tool_usage_style == "strict" %}
+You MUST use these tools to complete your tasks:
+{%- else %}
+You have access to these tools:
+{%- endif %}
+{% for tool in tools %}
+- {{ tool.name }}{% if tool.description %}: {{ tool.description }}{% endif %}
+{%- endfor %}
+
+{%- if tool_usage_style == "strict" %}
+Do not attempt to perform tasks without using appropriate tools.
+{%- else %}
+Use them when appropriate to complete your tasks.
+{%- endif %}
+
+{% endif -%}
+{% endif -%}
+{%- for prompt in prompts %}
+{{ prompt|to_prompt if dynamic else prompt }}
+{%- if not loop.last %}
+
+{% endif %}
+{%- endfor %}

agentpool/text_templates/tool_call_default.jinja

@@ -0,0 +1,13 @@
+Tool Call: {{ tool_name }}
+Arguments:
+{%- for name, value in args.items() %}
+  {{ name }}: {{ value|repr }}
+{%- endfor %}
+{%- if result %}
+
+Result: {{ result }}
+{%- endif %}
+{%- if error %}
+
+Error: {{ error }}
+{%- endif %}

agentpool/text_templates/tool_call_markdown.jinja

@@ -0,0 +1,25 @@
+### Tool Call: {{ tool_name }}
+
+**Arguments:**
+{% for name, value in args.items() %}
+- {{ name }}: {{ value|repr }}
+{%- endfor %}
+
+{%- if error %}
+
+**Error:** {{ error }}
+{%- endif %}
+{%- if result %}
+
+**Result:**
+```
+{{ result }}
+```
+{%- endif %}
+
+{%- if show_timing and timing %}
+*Execution time: {{ "%.2f"|format(timing) }}s*
+{%- endif %}
+{%- if agent_tool_name %}
+*Agent: {{ agent_tool_name }}*
+{%- endif %}

agentpool/text_templates/tool_call_simple.jinja

@@ -0,0 +1,5 @@
+{{ tool_name }}(
+    {%- for name, value in args.items() -%}
+        {{ name }}={{ value|repr }}{{ "," if not loop.last }}
+    {%- endfor -%}
+) -> {{ error if error else result }}

agentpool/tools/__init__.py

@@ -0,0 +1,16 @@
+"""Tool implementations and related classes / functions."""
+
+from __future__ import annotations
+
+from agentpool.tools.base import Tool
+from agentpool.tools.manager import ToolManager, ToolError
+from agentpool.tools.tool_call_info import ToolCallInfo
+from agentpool.skills.registry import SkillsRegistry
+
+__all__ = [
+    "SkillsRegistry",
+    "Tool",
+    "ToolCallInfo",
+    "ToolError",
+    "ToolManager",
+]

agentpool/tools/base.py

@@ -0,0 +1,269 @@
+"""Base tool classes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import inspect
+from typing import TYPE_CHECKING, Any, Literal
+
+import logfire
+from pydantic_ai.tools import Tool as PydanticAiTool
+import schemez
+
+from agentpool.log import get_logger
+from agentpool.utils.inspection import (
+    dataclasses_no_defaults_repr,
+    execute,
+    get_fn_name,
+    get_fn_qualname,
+)
+from agentpool_config.tools import ToolHints
+
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from mcp.types import Tool as MCPTool
+    from schemez import FunctionSchema, Property
+
+    from agentpool.common_types import ToolSource
+    from agentpool.tools.manager import ToolState
+
+
+logger = get_logger(__name__)
+ToolKind = Literal[
+    "read",
+    "edit",
+    "delete",
+    "move",
+    "search",
+    "execute",
+    "think",
+    "fetch",
+    "switch_mode",
+    "other",
+]
+
+
+@dataclass
+class Tool[TOutputType = Any]:
+    """Information about a registered tool."""
+
+    callable: Callable[..., TOutputType]
+    """The actual tool implementation"""
+
+    name: str
+    """The name of the tool."""
+
+    description: str = ""
+    """The description of the tool."""
+
+    schema_override: schemez.OpenAIFunctionDefinition | None = None
+    """Schema override. If not set, the schema is inferred from the callable."""
+
+    hints: ToolHints = field(default_factory=ToolHints)
+    """Hints for the tool."""
+
+    import_path: str | None = None
+    """The import path for the tool."""
+
+    enabled: bool = True
+    """Whether the tool is currently enabled"""
+
+    source: ToolSource | str = "dynamic"
+    """Where the tool came from."""
+
+    requires_confirmation: bool = False
+    """Whether tool execution needs explicit confirmation"""
+
+    agent_name: str | None = None
+    """The agent name as an identifier for agent-as-a-tool."""
+
+    metadata: dict[str, str] = field(default_factory=dict)
+    """Additional tool metadata"""
+
+    category: ToolKind | None = None
+    """The category of the tool."""
+
+    __repr__ = dataclasses_no_defaults_repr
+
+    def to_pydantic_ai(self) -> PydanticAiTool:
+        """Convert tool to Pydantic AI tool."""
+        metadata = {**self.metadata, "agent_name": self.agent_name, "category": self.category}
+        return PydanticAiTool(
+            function=self.callable,
+            name=self.name,
+            # takes_ctx=self.takes_ctx,
+            # max_retries=self.max_retries,
+            description=self.description,
+            requires_approval=self.requires_confirmation,
+            metadata=metadata,
+        )
+
+    @property
+    def schema_obj(self) -> FunctionSchema:
+        """Get the OpenAI function schema for the tool."""
+        from pydantic_ai import RunContext
+
+        from agentpool.agents.context import AgentContext
+
+        return schemez.create_schema(
+            self.callable,
+            name_override=self.name,
+            description_override=self.description,
+            exclude_types=[AgentContext, RunContext],
+        )
+
+    @property
+    def schema(self) -> schemez.OpenAIFunctionTool:
+        """Get the OpenAI function schema for the tool."""
+        schema = self.schema_obj.model_dump_openai()
+        if self.schema_override:
+            schema["function"] = self.schema_override
+        return schema
+
+    def matches_filter(self, state: ToolState) -> bool:
+        """Check if tool matches state filter."""
+        match state:
+            case "all":
+                return True
+            case "enabled":
+                return self.enabled
+            case "disabled":
+                return not self.enabled
+
+    @property
+    def parameters(self) -> list[ToolParameter]:
+        """Get information about tool parameters."""
+        schema = self.schema["function"]
+        properties: dict[str, Property] = schema.get("properties", {})  # type: ignore
+        required: list[str] = schema.get("required", [])  # type: ignore
+
+        return [
+            ToolParameter(
+                name=name,
+                required=name in required,
+                type_info=details.get("type"),
+                description=details.get("description"),
+            )
+            for name, details in properties.items()
+        ]
+
+    def format_info(self, indent: str = "  ") -> str:
+        """Format complete tool information."""
+        lines = [f"{indent}→ {self.name}"]
+        if self.description:
+            lines.append(f"{indent}  {self.description}")
+        if self.parameters:
+            lines.append(f"{indent}  Parameters:")
+            lines.extend(f"{indent}    {param}" for param in self.parameters)
+        if self.metadata:
+            lines.append(f"{indent}  Metadata:")
+            lines.extend(f"{indent}    {k}: {v}" for k, v in self.metadata.items())
+        return "\n".join(lines)
+
+    @logfire.instrument("Executing tool {self.name} with args={args}, kwargs={kwargs}")
+    async def execute(self, *args: Any, **kwargs: Any) -> Any:
+        """Execute tool, handling both sync and async cases."""
+        return await execute(self.callable, *args, **kwargs, use_thread=True)
+
+    @classmethod
+    def from_code(
+        cls,
+        code: str,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> Tool[Any]:
+        """Create a tool from a code string."""
+        namespace: dict[str, Any] = {}
+        exec(code, namespace)
+        func = next((v for v in namespace.values() if callable(v)), None)
+        if not func:
+            msg = "No callable found in provided code"
+            raise ValueError(msg)
+        return cls.from_callable(func, name_override=name, description_override=description)  # pyright: ignore[reportArgumentType]
+
+    @classmethod
+    def from_callable(
+        cls,
+        fn: Callable[..., TOutputType | Awaitable[TOutputType]] | str,
+        *,
+        name_override: str | None = None,
+        description_override: str | None = None,
+        schema_override: schemez.OpenAIFunctionDefinition | None = None,
+        hints: ToolHints | None = None,
+        category: ToolKind | None = None,
+        enabled: bool = True,
+        source: ToolSource | str | None = None,
+        **kwargs: Any,
+    ) -> Tool[TOutputType]:
+        if isinstance(fn, str):
+            import_path = fn
+            from agentpool.utils import importing
+
+            callable_obj = importing.import_callable(fn)
+            name = getattr(callable_obj, "__name__", "unknown")
+            import_path = fn
+        else:
+            callable_obj = fn
+            module = fn.__module__
+            if hasattr(fn, "__qualname__"):  # Regular function
+                name = get_fn_name(fn)
+                import_path = f"{module}.{get_fn_qualname(fn)}"
+            else:  # Instance with __call__ method
+                name = fn.__class__.__name__
+                import_path = f"{module}.{fn.__class__.__qualname__}"
+
+        return cls(
+            callable=callable_obj,  # pyright: ignore[reportArgumentType]
+            name=name_override or name,
+            description=description_override or inspect.getdoc(callable_obj) or "",
+            import_path=import_path,
+            schema_override=schema_override,
+            category=category,
+            hints=hints or ToolHints(),
+            enabled=enabled,
+            source=source or "dynamic",
+            **kwargs,
+        )
+
+    def to_mcp_tool(self) -> MCPTool:
+        """Convert internal Tool to MCP Tool."""
+        schema = self.schema
+        from mcp.types import Tool as MCPTool, ToolAnnotations
+
+        return MCPTool(
+            name=schema["function"]["name"],
+            description=schema["function"]["description"],
+            inputSchema=schema["function"]["parameters"],  # pyright: ignore
+            annotations=ToolAnnotations(
+                title=self.name,
+                readOnlyHint=self.hints.read_only if self.hints else None,
+                destructiveHint=self.hints.destructive if self.hints else None,
+                idempotentHint=self.hints.idempotent if self.hints else None,
+                openWorldHint=self.hints.open_world if self.hints else None,
+            ),
+        )
+
+
+@dataclass
+class ToolParameter:
+    """Information about a tool parameter."""
+
+    name: str
+    required: bool
+    type_info: str | None = None
+    description: str | None = None
+
+    def __str__(self) -> str:
+        """Format parameter info."""
+        req = "*" if self.required else ""
+        type_str = f": {self.type_info}" if self.type_info else ""
+        desc = f" - {self.description}" if self.description else ""
+        return f"{self.name}{req}{type_str}{desc}"
+
+
+if __name__ == "__main__":
+    import webbrowser
+
+    t = Tool.from_callable(webbrowser.open)

agentpool/tools/exceptions.py

@@ -0,0 +1,9 @@
+"""Tool-related exceptions."""
+
+from __future__ import annotations
+
+from agentpool.utils.baseregistry import AgentPoolError
+
+
+class ToolError(AgentPoolError):
+    """Tool-related errors."""