agentpool 2.1.9__py3-none-any.whl

agentpool_toolsets/builtin/subagent_tools.py

@@ -0,0 +1,324 @@
+"""Provider for subagent interaction tools with streaming support."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic_ai import (
+    FunctionToolCallEvent,
+    FunctionToolResultEvent,
+    ModelRetry,
+    PartDeltaEvent,
+    PartStartEvent,
+    RetryPromptPart,
+    TextPart,
+    TextPartDelta,
+    ThinkingPart,
+    ThinkingPartDelta,
+    ToolCallPartDelta,
+    ToolReturnPart,
+)
+
+from agentpool.agents.context import AgentContext  # noqa: TC001
+from agentpool.log import get_logger
+from agentpool.resource_providers import StaticResourceProvider
+from agentpool.tools.exceptions import ToolError
+
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from agentpool.agents.events import RichAgentStreamEvent
+
+
+logger = get_logger(__name__)
+
+
+# Delta type identifiers for batching
+type _DeltaType = Literal["text", "thinking", "tool_call"] | None
+
+
+async def batch_stream_deltas(  # noqa: PLR0915
+    stream: AsyncIterator[RichAgentStreamEvent[Any]],
+) -> AsyncIterator[RichAgentStreamEvent[Any]]:
+    """Batch consecutive delta events, yielding when event type changes.
+
+    This reduces UI update frequency by accumulating consecutive deltas of the same
+    type and yielding them as a single event when the type changes.
+
+    Batches:
+    - TextPartDelta events (consecutive deltas combined into one)
+    - ThinkingPartDelta events (consecutive deltas combined into one)
+    - ToolCallPartDelta events (consecutive deltas combined into one)
+
+    All other events pass through immediately and flush any pending batch.
+    PartStartEvents pass through unchanged.
+
+    Args:
+        stream: Async iterator of stream events from agent.run_stream()
+
+    Yields:
+        Stream events with consecutive deltas batched together
+    """
+    pending_content: list[str] = []
+    pending_type: _DeltaType = None
+    pending_index: int = 0  # For PartDeltaEvent.index
+
+    def _make_batched_event() -> PartDeltaEvent:
+        """Create a synthetic PartDeltaEvent from accumulated content."""
+        content = "".join(pending_content)
+        delta: TextPartDelta | ThinkingPartDelta | ToolCallPartDelta
+        match pending_type:
+            case "text":
+                delta = TextPartDelta(content_delta=content)
+            case "thinking":
+                delta = ThinkingPartDelta(content_delta=content)
+            case "tool_call":
+                delta = ToolCallPartDelta(args_delta=content)
+            case _:
+                msg = f"Unexpected pending type: {pending_type}"
+                raise ValueError(msg)
+        return PartDeltaEvent(index=pending_index, delta=delta)
+
+    async for event in stream:
+        match event:
+            case PartDeltaEvent(delta=TextPartDelta(content_delta=content), index=idx):
+                if pending_type == "text":
+                    pending_content.append(content)
+                else:
+                    if pending_type is not None and pending_content:
+                        yield _make_batched_event()
+                    pending_content = [content]
+                    pending_type = "text"
+                    pending_index = idx
+
+            case PartDeltaEvent(delta=ThinkingPartDelta(content_delta=content), index=idx):
+                if content is None:
+                    continue
+                if pending_type == "thinking":
+                    pending_content.append(content)
+                else:
+                    if pending_type is not None and pending_content:
+                        yield _make_batched_event()
+                    pending_content = [content]
+                    pending_type = "thinking"
+                    pending_index = idx
+
+            case PartDeltaEvent(delta=ToolCallPartDelta(args_delta=args), index=idx) if isinstance(
+                args, str
+            ):
+                if pending_type == "tool_call":
+                    pending_content.append(args)
+                else:
+                    if pending_type is not None and pending_content:
+                        yield _make_batched_event()
+                    pending_content = [args]
+                    pending_type = "tool_call"
+                    pending_index = idx
+
+            case _:
+                # Any other event: flush pending batch and pass through
+                if pending_type is not None and pending_content:
+                    yield _make_batched_event()
+                    pending_content = []
+                    pending_type = None
+                yield event
+
+    # Flush any remaining batch at end of stream
+    if pending_type is not None and pending_content:
+        yield _make_batched_event()
+
+
+async def _stream_agent_with_progress(
+    ctx: AgentContext,
+    stream: AsyncIterator[RichAgentStreamEvent[Any]],
+    *,
+    batch_deltas: bool = False,
+) -> str:
+    """Stream an agent's execution and emit progress events.
+
+    Args:
+        ctx: Agent context for emitting events
+        stream: Async iterator of stream events from agent.run_stream()
+        batch_deltas: If True, batch consecutive text/thinking deltas for fewer UI updates
+
+    Returns:
+        Aggregated content from the stream
+    """
+    if batch_deltas:
+        stream = batch_stream_deltas(stream)
+
+    aggregated: list[str] = []
+    async for event in stream:
+        match event:
+            case (
+                PartStartEvent(part=TextPart(content=delta))
+                | PartDeltaEvent(delta=TextPartDelta(content_delta=delta))
+            ):
+                aggregated.append(delta)
+                await ctx.events.tool_call_progress("".join(aggregated))
+            case (
+                PartStartEvent(part=ThinkingPart(content=delta))
+                | PartDeltaEvent(delta=ThinkingPartDelta(content_delta=delta))
+            ):
+                if delta:
+                    aggregated.append(f"💭 {delta}")
+                    await ctx.events.tool_call_progress("".join(aggregated))
+            case FunctionToolCallEvent(part=part):
+                aggregated.append(f"\n🔧 Using tool: {part.tool_name}\n")
+                await ctx.events.tool_call_progress("".join(aggregated))
+            case FunctionToolResultEvent(
+                result=ToolReturnPart(content=content, tool_name=tool_name),
+            ):
+                aggregated.append(f"✅ {tool_name}: {content}\n")
+                await ctx.events.tool_call_progress("".join(aggregated))
+
+            case FunctionToolResultEvent(result=RetryPromptPart(tool_name=tool_name) as result):
+                error_message = result.model_response()
+                aggregated.append(f"❌ {tool_name or 'unknown'}: {error_message}\n")
+                await ctx.events.tool_call_progress("".join(aggregated))
+            case _:
+                pass
+
+    return "".join(aggregated).strip()
+
+
+class SubagentTools(StaticResourceProvider):
+    """Provider for subagent interaction tools with streaming progress."""
+
+    def __init__(
+        self,
+        name: str = "subagent_tools",
+        *,
+        batch_stream_deltas: bool = False,
+    ) -> None:
+        super().__init__(name=name)
+        self._batch_stream_deltas = batch_stream_deltas
+        for tool in [
+            self.create_tool(
+                self.list_available_nodes, category="search", read_only=True, idempotent=True
+            ),
+            self.create_tool(self.delegate_to, category="other"),
+            self.create_tool(self.ask_agent, category="other"),
+        ]:
+            self.add_tool(tool)
+
+    async def list_available_nodes(  # noqa: D417
+        self,
+        ctx: AgentContext,
+        node_type: Literal["all", "agent", "team"] = "all",
+        only_idle: bool = False,
+    ) -> str:
+        """List available agents and/or teams in the current pool.
+
+        Args:
+            node_type: Filter by node type - "all", "agent", or "team"
+            only_idle: If True, only returns nodes that aren't currently busy
+
+        Returns:
+            List of node names that you can use with delegate_to or ask_agent
+        """
+        from agentpool import Agent
+
+        if not ctx.pool:
+            msg = "No agent pool available"
+            raise ToolError(msg)
+        lines: list[str] = []
+        if node_type in ("all", "agent"):
+            agents = dict(ctx.pool.all_agents)
+            if only_idle:
+                agents = {
+                    n: a for n, a in agents.items() if not (isinstance(a, Agent) and a.is_busy())
+                }
+            for name, agent in agents.items():
+                lines.extend([
+                    f"name: {name}",
+                    "type: agent",
+                    f"description: {agent.description or 'No description'}",
+                    "---",
+                ])
+
+        if node_type in ("all", "team"):  # List teams
+            teams = ctx.pool.teams
+            if only_idle:
+                teams = {name: team for name, team in teams.items() if not team.is_running}
+            for name, team in teams.items():
+                lines.extend([
+                    f"name: {name}",
+                    f"description: {team.description or 'No description'}",
+                    "---",
+                ])
+
+        return "\n".join(lines) if lines else "No nodes available"
+
+    async def delegate_to(  # noqa: D417
+        self,
+        ctx: AgentContext,
+        agent_or_team_name: str,
+        prompt: str,
+    ) -> str:
+        """Delegate a task to an agent or team.
+
+        If an action requires you to delegate a task, this tool can be used to assign and
+        execute a task. Instructions can be passed via the prompt parameter.
+
+        Args:
+            agent_or_team_name: The agent or team to delegate the task to
+            prompt: Instructions for the agent or team to delegate to.
+
+        Returns:
+            The result of the delegated task
+        """
+        if not ctx.pool:
+            msg = "Agent needs to be in a pool to delegate tasks"
+            raise ToolError(msg)
+        if agent_or_team_name not in ctx.pool.nodes:
+            msg = (
+                f"No agent or team found with name: {agent_or_team_name}. "
+                f"Available nodes: {', '.join(ctx.pool.nodes.keys())}"
+            )
+            raise ModelRetry(msg)
+
+        # For teams, use simple run() - no streaming support yet
+        if agent_or_team_name in ctx.pool.teams:
+            result = await ctx.pool.teams[agent_or_team_name].run(prompt)
+            return result.format(style="detailed", show_costs=True)
+        # For agents (regular or ACP), stream with progress events
+        agent = ctx.pool.all_agents[agent_or_team_name]
+        return await _stream_agent_with_progress(
+            ctx, agent.run_stream(prompt), batch_deltas=self._batch_stream_deltas
+        )
+
+    async def ask_agent(  # noqa: D417
+        self,
+        ctx: AgentContext,
+        agent_name: str,
+        message: str,
+    ) -> str:
+        """Send a message to a specific agent and get their response.
+
+        Args:
+            agent_name: Name of the agent to interact with
+            message: Message to send to the agent
+
+        Returns:
+            The agent's response
+        """
+        if not ctx.pool:
+            msg = "No agent pool available"
+            raise ToolError(msg)
+
+        if agent_name not in ctx.pool.all_agents:
+            available = list(ctx.pool.all_agents.keys())
+            names = ", ".join(available)
+            raise ModelRetry(f"Agent not found: {agent_name}. Available agents: {names}")
+
+        agent = ctx.pool.all_agents[agent_name]
+        try:
+            stream = agent.run_stream(message)
+            return await _stream_agent_with_progress(
+                ctx, stream, batch_deltas=self._batch_stream_deltas
+            )
+        except Exception as e:
+            msg = f"Failed to ask agent {agent_name}: {e}"
+            raise ModelRetry(msg) from e

agentpool_toolsets/builtin/tool_management.py

@@ -0,0 +1,90 @@
+"""Provider for tool management tools."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from agentpool.agents.context import AgentContext  # noqa: TC001
+from agentpool.resource_providers import StaticResourceProvider
+from agentpool.tools.base import Tool
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+
+async def register_tool(  # noqa: D417
+    ctx: AgentContext,
+    tool: str | Callable[..., Any],
+    name: str | None = None,
+    description: str | None = None,
+    enabled: bool = True,
+) -> str:
+    """Register a new tool from callable or import path.
+
+    Args:
+        tool: Callable function or import path string to register as tool
+        name: Optional name override for the tool
+        description: Optional description override for the tool
+        enabled: Whether the tool should be enabled initially
+
+    Returns:
+        Confirmation message with registered tool name
+    """
+    # Create tool from callable/import path
+    tool_obj = Tool.from_callable(
+        tool,
+        name_override=name,
+        description_override=description,
+        source="dynamic",
+        enabled=enabled,
+    )
+
+    # Register with the agent's tool manager
+    registered_tool = ctx.agent.tools.register_tool(tool_obj)
+
+    return f"Successfully registered tool: {registered_tool.name}"
+
+
+async def register_code_tool(  # noqa: D417
+    ctx: AgentContext,
+    code: str,
+    name: str | None = None,
+    description: str | None = None,
+    enabled: bool = True,
+) -> str:
+    """Register a new tool from code string.
+
+    Args:
+        code: Python code string containing a callable function
+        name: Optional name override for the tool
+        description: Optional description override for the tool
+        enabled: Whether the tool should be enabled initially
+
+    Returns:
+        Confirmation message with registered tool name
+    """
+    # Create tool from code
+    tool_obj = Tool.from_code(
+        code,
+        name=name,
+        description=description,
+    )
+    tool_obj.enabled = enabled
+    tool_obj.source = "dynamic"
+
+    # Register with the agent's tool manager
+    registered_tool = ctx.agent.tools.register_tool(tool_obj)
+
+    return f"Successfully registered code tool: {registered_tool.name}"
+
+
+class ToolManagementTools(StaticResourceProvider):
+    """Provider for tool management tools."""
+
+    def __init__(self, name: str = "tool_management") -> None:
+        super().__init__(name=name)
+        self._tools = [
+            self.create_tool(register_tool, category="other"),
+            self.create_tool(register_code_tool, category="other"),
+        ]

agentpool_toolsets/builtin/user_interaction.py

@@ -0,0 +1,52 @@
+"""Provider for user interaction tools."""
+
+from __future__ import annotations
+
+from typing import Any, assert_never
+
+from agentpool.agents.context import AgentContext  # noqa: TC001
+from agentpool.resource_providers import StaticResourceProvider
+
+
+async def ask_user(  # noqa: D417
+    ctx: AgentContext,
+    prompt: str,
+    response_schema: dict[str, Any] | None = None,
+) -> str:
+    """Allow LLM to ask user a clarifying question during processing.
+
+    This tool enables agents to ask users for additional information or clarification
+    when needed to complete a task effectively.
+
+    Args:
+        prompt: Question to ask the user
+        response_schema: Optional JSON schema for structured response (defaults to string)
+
+    Returns:
+        The user's response as a string
+    """
+    from mcp.types import ElicitRequestFormParams, ElicitResult, ErrorData
+
+    schema = response_schema or {"type": "string"}  # string schema if no none provided
+    params = ElicitRequestFormParams(message=prompt, requestedSchema=schema)
+    result = await ctx.handle_elicitation(params)
+
+    match result:
+        case ElicitResult(action="accept", content=content):
+            return str(content)
+        case ElicitResult(action="cancel"):
+            return "User cancelled the request"
+        case ElicitResult():
+            return "User declined to answer"
+        case ErrorData(message=message):
+            return f"Error: {message}"
+        case _ as unreachable:
+            assert_never(unreachable)
+
+
+class UserInteractionTools(StaticResourceProvider):
+    """Provider for user interaction tools."""
+
+    def __init__(self, name: str = "user_interaction") -> None:
+        super().__init__(name=name)
+        self._tools = [self.create_tool(ask_user, category="other", open_world=True)]

agentpool_toolsets/builtin/workers.py

@@ -0,0 +1,128 @@
+"""Provider for worker agent tools."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from agentpool.agents.context import AgentContext  # noqa: TC001
+from agentpool.log import get_logger
+from agentpool.resource_providers import ResourceProvider
+from agentpool.tools.exceptions import ToolError
+
+
+if TYPE_CHECKING:
+    from agentpool.tools.base import Tool
+    from agentpool_config.workers import WorkerConfig
+
+logger = get_logger(__name__)
+
+
+class WorkersTools(ResourceProvider):
+    """Provider for worker agent tools.
+
+    Creates tools for each configured worker that delegate to agents/teams in the pool.
+    Tools are created lazily when get_tools() is called, using AgentContext to access
+    the pool at call time.
+    """
+
+    def __init__(self, workers: list[WorkerConfig], name: str = "workers") -> None:
+        """Initialize workers toolset.
+
+        Args:
+            workers: List of worker configurations
+            name: Provider name
+        """
+        super().__init__(name=name)
+        self.workers = workers
+
+    async def get_tools(self) -> list[Tool]:
+        """Get tools for all configured workers."""
+        return [self._create_worker_tool(i) for i in self.workers]
+
+    def _create_worker_tool(self, worker_config: WorkerConfig) -> Tool:
+        """Create a tool for a single worker configuration."""
+        from agentpool_config.workers import AgentWorkerConfig
+
+        worker_name = worker_config.name
+        # Regular agents get history management
+        if isinstance(worker_config, AgentWorkerConfig):
+            return self._create_agent_tool(
+                worker_name,
+                reset_history_on_run=worker_config.reset_history_on_run,
+                pass_message_history=worker_config.pass_message_history,
+            )
+        # Teams, ACP agents, AGUI agents - all handled uniformly
+        return self._create_node_tool(worker_name)
+
+    def _create_agent_tool(
+        self,
+        agent_name: str,
+        *,
+        reset_history_on_run: bool = True,
+        pass_message_history: bool = False,
+    ) -> Tool:
+        """Create tool for a regular agent worker with history management."""
+
+        async def run(ctx: AgentContext, prompt: str) -> Any:
+            if not ctx.pool:
+                msg = "No agent pool available"
+                raise ToolError(msg)
+            if agent_name not in ctx.pool.agents:
+                msg = f"Agent {agent_name!r} not found in pool"
+                raise ToolError(msg)
+
+            worker = ctx.pool.agents[agent_name]
+            old_history = None
+
+            if pass_message_history:
+                old_history = worker.conversation.get_history()
+                worker.conversation.set_history(ctx.agent.conversation.get_history())
+            elif reset_history_on_run:
+                worker.conversation.clear()
+
+            try:
+                result = await worker.run(prompt)
+                return result.data
+            finally:
+                if old_history is not None:
+                    worker.conversation.set_history(old_history)
+
+        tool_name = f"ask_{agent_name}"
+        normalized_name = agent_name.replace("_", " ").title()
+        docstring = f"Get expert answer from specialized agent: {normalized_name}"
+
+        run.__name__ = tool_name
+        run.__doc__ = docstring
+
+        return self.create_tool(run, name_override=tool_name, description_override=docstring)
+
+    def _create_node_tool(self, node_name: str) -> Tool:
+        """Create tool for non-agent nodes (teams, ACP agents, AGUI agents)."""
+        from agentpool import BaseTeam
+
+        async def run(ctx: AgentContext, prompt: str) -> str:
+            if not ctx.pool:
+                msg = "No agent pool available"
+                raise ToolError(msg)
+            if node_name not in ctx.pool.nodes:
+                msg = f"Worker {node_name!r} not found in pool"
+                raise ToolError(msg)
+
+            worker = ctx.pool.nodes[node_name]
+            result = await worker.run(prompt)
+
+            # Teams get formatted output
+            if isinstance(worker, BaseTeam):
+                return result.format(style="detailed", show_costs=True)
+
+            # Other nodes (ACP, AGUI) just return data as string
+            return str(result.data)
+
+        tool_name = f"ask_{node_name}"
+        normalized_name = node_name.replace("_", " ").title()
+        docstring = f"Delegate task to worker: {normalized_name}"
+
+        run.__name__ = tool_name
+        run.__doc__ = docstring
+
+        return self.create_tool(run, name_override=tool_name, description_override=docstring)

agentpool_toolsets/composio_toolset.py

@@ -0,0 +1,96 @@
+"""Composio based toolset implementation."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any
+
+from agentpool.log import get_logger
+from agentpool.resource_providers import ResourceProvider
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from agentpool.tools.base import Tool
+
+
+logger = get_logger(__name__)
+
+
+class ComposioTools(ResourceProvider):
+    """Provider for composio tools."""
+
+    def __init__(self, user_id: str, toolsets: list[str], api_key: str | None = None) -> None:
+        from composio import Composio
+        from composio.core.provider._openai import OpenAIProvider
+
+        super().__init__(name=f"composio_{user_id}")
+        self.user_id = user_id
+        key = api_key or os.environ.get("COMPOSIO_API_KEY")
+        if key:
+            self.composio = Composio[OpenAIProvider](api_key=key)
+        else:
+            self.composio = Composio[OpenAIProvider]()
+        self._tools: list[Tool] | None = None
+        self._toolkits = toolsets
+
+    def _create_tool_handler(self, tool_slug: str) -> Callable[..., Any]:
+        """Create a handler function for a specific tool."""
+
+        def handle_tool_call(**kwargs: Any) -> Any:
+            try:
+                return self.composio.tools.execute(
+                    slug=tool_slug,
+                    arguments=kwargs,
+                    user_id=self.user_id,
+                )
+            except Exception:
+                logger.exception("Error executing tool", name=tool_slug)
+                return {"error": f"Failed to execute tool {tool_slug}"}
+
+        handle_tool_call.__name__ = tool_slug
+        return handle_tool_call
+
+    async def get_tools(self) -> list[Tool]:
+        """Get tools from composio."""
+        # Return cached tools if available
+        if self._tools is not None:
+            return self._tools
+
+        self._tools = []
+
+        try:
+            # Get tools for GitHub toolkit using v3 API
+            tools = self.composio.tools.get(self.user_id, toolkits=self._toolkits)
+
+            for tool_def in tools:
+                # In v3 SDK, tools are OpenAI formatted by default
+                if isinstance(tool_def, dict) and "function" in tool_def:
+                    tool_slug = tool_def["function"].get("name", "")
+                    if tool_slug:
+                        fn = self._create_tool_handler(tool_slug)
+                        tool = self.create_tool(fn, schema_override=tool_def["function"])
+                        self._tools.append(tool)
+
+        except Exception:
+            logger.exception("Error getting Composio tools")
+            # Return empty list if there's an error
+            self._tools = []
+
+        return self._tools
+
+
+if __name__ == "__main__":
+    import anyio
+
+    async def main() -> None:
+        from agentpool import Agent
+
+        tools = ComposioTools("user@example.com", toolsets=["github"])
+        agent = Agent(model="gpt-5-nano")
+        agent.tools.add_provider(tools)
+        result = await agent.run("tell me the tools at your disposal")
+        print(result)
+
+    anyio.run(main)