agentpool 2.2.3__py3-none-any.whl → 2.5.0__py3-none-any.whl

agentpool/agents/agent.py

@@ -3,18 +3,15 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Awaitable, Callable
-from contextlib import AsyncExitStack, asynccontextmanager, suppress
-from dataclasses import dataclass, field, replace
+from collections.abc import Awaitable
+from contextlib import AsyncExitStack, asynccontextmanager
+from dataclasses import replace
 import time
 from typing import TYPE_CHECKING, Any, Self, TypedDict, TypeVar, overload
 from uuid import uuid4
 
 from anyenv import method_spawner
-import anyio
-from llmling_models import function_to_model, infer_model
 import logfire
-from psygnal import Signal
 from pydantic import ValidationError
 from pydantic._internal import _typing_extra
 from pydantic_ai import (
@@ -28,6 +25,7 @@ from pydantic_ai import (
     RunContext,
     ToolReturnPart,
 )
+from pydantic_ai.models import Model
 
 from agentpool.agents.base_agent import BaseAgent
 from agentpool.agents.events import (
@@ -35,59 +33,27 @@ from agentpool.agents.events import (
     StreamCompleteEvent,
     ToolCallCompleteEvent,
 )
+from agentpool.agents.events.processors import FileTracker
 from agentpool.agents.modes import ModeInfo
 from agentpool.log import get_logger
-from agentpool.messaging import ChatMessage, MessageHistory, MessageNode
-from agentpool.messaging.processing import prepare_prompts
+from agentpool.messaging import ChatMessage, MessageHistory
 from agentpool.prompts.convert import convert_prompts
 from agentpool.storage import StorageManager
 from agentpool.tools import Tool, ToolManager
 from agentpool.tools.exceptions import ToolError
-from agentpool.utils.inspection import call_with_context, get_argument_key
-from agentpool.utils.now import get_now
+from agentpool.utils.inspection import get_argument_key
 from agentpool.utils.pydantic_ai_helpers import safe_args_as_dict
 from agentpool.utils.result_utils import to_type
-from agentpool.utils.streams import FileTracker, merge_queue_into_iterator
-
-
-TResult = TypeVar("TResult")
-
-
-def _extract_text_from_messages(
-    messages: list[Any], include_interruption_note: bool = False
-) -> str:
-    """Extract text content from pydantic-ai messages.
-
-    Args:
-        messages: List of ModelRequest/ModelResponse messages
-        include_interruption_note: Whether to append interruption notice
-
-    Returns:
-        Concatenated text content from all ModelResponse TextParts
-    """
-    from pydantic_ai.messages import ModelResponse, TextPart as PydanticTextPart
-
-    content = "".join(
-        part.content
-        for msg in messages
-        if isinstance(msg, ModelResponse)
-        for part in msg.parts
-        if isinstance(part, PydanticTextPart)
-    )
-    if include_interruption_note:
-        if content:
-            content += "\n\n"
-        content += "[Request interrupted by user]"
-    return content
+from agentpool.utils.streams import merge_queue_into_iterator
 
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator, Coroutine, Sequence
-    from datetime import datetime
+    from collections.abc import AsyncIterator, Callable, Coroutine, Sequence
     from types import TracebackType
 
     from exxec import ExecutionEnvironment
-    from pydantic_ai import UsageLimits
+    from llmling_models_config import AnyModelConfig
+    from pydantic_ai import UsageLimits, UserContent
     from pydantic_ai.builtin_tools import AbstractBuiltinTool
     from pydantic_ai.output import OutputSpec
     from pydantic_ai.settings import ModelSettings
@@ -101,21 +67,22 @@ if TYPE_CHECKING:
     from agentpool.agents.events import RichAgentStreamEvent
     from agentpool.agents.modes import ModeCategory
     from agentpool.common_types import (
-        AgentName,
         BuiltinEventHandlerType,
         EndStrategy,
         IndividualEventHandler,
         ModelType,
         ProcessorCallback,
-        PromptCompatible,
         SessionIdType,
         ToolType,
     )
-    from agentpool.delegation import AgentPool, Team, TeamRun
+    from agentpool.delegation import AgentPool
     from agentpool.hooks import AgentHooks
+    from agentpool.messaging import MessageNode
     from agentpool.models.agents import NativeAgentConfig, ToolMode
+    from agentpool.models.manifest import AgentsManifest
     from agentpool.prompts.prompts import PromptType
     from agentpool.resource_providers import ResourceProvider
+    from agentpool.tools.base import FunctionTool
     from agentpool.ui.base import InputProvider
     from agentpool_config.knowledge import Knowledge
     from agentpool_config.mcp_server import MCPServerConfig
@@ -128,6 +95,36 @@ logger = get_logger(__name__)
 # OutputDataT = TypeVar('OutputDataT', default=str, covariant=True)
 NoneType = type(None)
 
+TResult = TypeVar("TResult")
+
+
+def _extract_text_from_messages(
+    messages: list[Any], include_interruption_note: bool = False
+) -> str:
+    """Extract text content from pydantic-ai messages.
+
+    Args:
+        messages: List of ModelRequest/ModelResponse messages
+        include_interruption_note: Whether to append interruption notice
+
+    Returns:
+        Concatenated text content from all ModelResponse TextParts
+    """
+    from pydantic_ai.messages import ModelResponse, TextPart as PydanticTextPart
+
+    content = "".join(
+        part.content
+        for msg in messages
+        if isinstance(msg, ModelResponse)
+        for part in msg.parts
+        if isinstance(part, PydanticTextPart)
+    )
+    if include_interruption_note:
+        if content:
+            content += "\n\n"
+        content += "[Request interrupted by user]"
+    return content
+
 
 class AgentKwargs(TypedDict, total=False):
     """Keyword arguments for configuring an Agent instance."""
@@ -160,25 +157,13 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
     Generically typed with: Agent[Type of Dependencies, Type of Result]
     """
 
-    @dataclass(frozen=True)
-    class AgentReset:
-        """Emitted when agent is reset."""
-
-        agent_name: AgentName
-        previous_tools: dict[str, bool]
-        new_tools: dict[str, bool]
-        timestamp: datetime = field(default_factory=get_now)
-
-    run_failed = Signal(str, Exception)
-    agent_reset = Signal(AgentReset)
-
-    def __init__(
+    def __init__(  # noqa: PLR0915
         # we dont use AgentKwargs here so that we can work with explicit ones in the ctor
         self,
         name: str = "agentpool",
         *,
         deps_type: type[TDeps] | None = None,
-        model: ModelType = None,
+        model: ModelType,
         output_type: OutputSpec[OutputDataT] = str,  # type: ignore[assignment]
         # context: AgentContext[TDeps] | None = None,
         session: SessionIdType | SessionQuery | MemoryConfig | bool | int = None,
@@ -250,18 +235,21 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
             hooks: AgentHooks instance for intercepting agent behavior at run and tool events
             tool_confirmation_mode: Tool confirmation mode
             builtin_tools: PydanticAI builtin tools (WebSearchTool, CodeExecutionTool, etc.)
-            usage_limits: Usage limits for the agent
+            usage_limits: Per-request usage limits (applied to each run() call independently,
+                not cumulative across the session)
             providers: Model providers for model discovery (e.g., ["openai", "anthropic"]).
                 Defaults to ["models.dev"] if not specified.
             commands: Slash commands
         """
+        from llmling_models_config import StringModelConfig
+
         from agentpool.agents.interactions import Interactions
         from agentpool.agents.sys_prompts import SystemPrompts
         from agentpool.models.agents import NativeAgentConfig
         from agentpool.prompts.conversion_manager import ConversionManager
+        from agentpool_commands.pool import CompactCommand
         from agentpool_config.session import MemoryConfig
 
-        self._infinite = False
         self.deps_type = deps_type
         self.model_settings = model_settings
         memory_cfg = (
@@ -271,7 +259,10 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
         all_mcp_servers = list(mcp_servers) if mcp_servers else []
         if agent_config and agent_config.mcp_servers:
             all_mcp_servers.extend(agent_config.get_mcp_servers())
-
+        # Add CompactCommand - only makes sense for Native Agent (has own history)
+        # Other agents (ClaudeCode, ACP, AGUI) don't control their history directly
+        all_commands = list(commands) if commands else []
+        all_commands.append(CompactCommand())
         # Call base class with shared parameters
         super().__init__(
             name=name,
@@ -286,15 +277,28 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
             output_type=to_type(output_type),  # type: ignore[arg-type]
             tool_confirmation_mode=tool_confirmation_mode,
             event_handlers=event_handlers,
-            commands=commands,
+            commands=all_commands,
         )
 
         # Store config for context creation
-        self._agent_config = agent_config or NativeAgentConfig(name=name)
+        # Convert model to proper config type for NativeAgentConfig
 
+        config_model: AnyModelConfig
+        if isinstance(model, Model):
+            config_model = StringModelConfig(
+                identifier=model.model_name,
+                **({"model_settings": model._settings} if model._settings else {}),
+            )
+        elif isinstance(model, str):
+            config_model = StringModelConfig(
+                identifier=model,
+                **({"model_settings": model_settings} if model_settings else {}),
+            )
+        else:
+            config_model = model
+        self._agent_config = agent_config or NativeAgentConfig(name=name, model=config_model)
         # Store builtin tools for pydantic-ai
         self._builtin_tools = list(builtin_tools) if builtin_tools else []
-
         # Override tools with Agent-specific ToolManager (with tools and tool_mode)
         all_tools = list(tools or [])
         self.tools = ToolManager(all_tools, tool_mode=tool_mode)
@@ -302,7 +306,6 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
             self.tools.add_provider(toolset_provider)
         aggregating_provider = self.mcp.get_aggregating_provider()
         self.tools.add_provider(aggregating_provider)
-
         # Override conversation with Agent-specific MessageHistory (with storage, etc.)
         resources = list(resources)
         if knowledge:
@@ -314,14 +317,17 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
             session_config=memory_cfg,
             resources=resources,
         )
-        self._model = infer_model(model) if isinstance(model, str) else model
+        if isinstance(model, str):
+            self._model, settings = self._resolve_model_string(model)
+            if settings:
+                self.model_settings = settings
+        else:
+            self._model = model
         self._retries = retries
         self._end_strategy: EndStrategy = end_strategy
         self._output_retries = output_retries
         self.parallel_init = parallel_init
-        self._background_task: asyncio.Task[ChatMessage[Any]] | None = None
         self.talk = Interactions(self)
-
         # Set up system prompts
         all_prompts: list[AnyPromptType] = []
         if isinstance(system_prompt, (list, tuple)):
@@ -329,13 +335,10 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
         elif system_prompt:
             all_prompts.append(system_prompt)
         self.sys_prompts = SystemPrompts(all_prompts, prompt_manager=self._manifest.prompt_manager)
-
         # Store hooks
         self.hooks = hooks
-
         # Store default usage limits
         self._default_usage_limits = usage_limits
-
         # Store providers for model discovery
         self._providers = list(providers) if providers else None
 
@@ -352,6 +355,143 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
         parts.extend([await self.tools.__prompt__(), self.conversation.__prompt__()])
         return "\n".join(parts)
 
+    @classmethod
+    def from_config(  # noqa: PLR0915
+        cls,
+        config: NativeAgentConfig,
+        *,
+        name: str | None = None,
+        manifest: AgentsManifest | None = None,
+        event_handlers: Sequence[IndividualEventHandler | BuiltinEventHandlerType] | None = None,
+        input_provider: InputProvider | None = None,
+        agent_pool: AgentPool[Any] | None = None,
+        deps_type: type[TDeps] | None = None,
+    ) -> Self:
+        """Create a native Agent from a config object.
+
+        This is the preferred way to instantiate an Agent from configuration.
+        Handles system prompt resolution, model resolution, toolsets setup, etc.
+
+        Args:
+            config: Native agent configuration
+            name: Optional name override (used for manifest lookups, defaults to config.name)
+            manifest: Optional manifest for resolving prompts, models, output types.
+                     If not provided, uses agent_pool.manifest or creates empty one.
+            event_handlers: Optional event handlers (merged with config handlers)
+            input_provider: Optional input provider for user interactions
+            agent_pool: Optional agent pool for coordination
+            deps_type: Optional dependency type
+
+        Returns:
+            Configured Agent instance
+        """
+        from pathlib import Path
+
+        from agentpool.models.manifest import AgentsManifest
+        from agentpool.utils.result_utils import to_type
+        from agentpool_config.system_prompts import (
+            FilePromptConfig,
+            FunctionPromptConfig,
+            LibraryPromptConfig,
+            StaticPromptConfig,
+        )
+
+        # Get manifest from pool or create empty one
+        if manifest is None:
+            manifest = agent_pool.manifest if agent_pool else AgentsManifest()
+
+        # Use provided name, fall back to config.name, then default
+        name = name or config.name or "agent"
+
+        # Normalize system_prompt to a list for iteration
+        sys_prompts: list[str] = []
+        prompt_source = config.system_prompt
+        if prompt_source is not None:
+            prompts_to_process = (
+                [prompt_source] if isinstance(prompt_source, str) else prompt_source
+            )
+            for prompt in prompts_to_process:
+                match prompt:
+                    case (str() as sys_prompt) | StaticPromptConfig(content=sys_prompt):
+                        sys_prompts.append(sys_prompt)
+                    case FilePromptConfig(path=path, variables=variables):
+                        template_path = Path(path)
+                        if not template_path.is_absolute() and config.config_file_path:
+                            template_path = Path(config.config_file_path).parent / path
+                        template_content = template_path.read_text("utf-8")
+                        if variables:
+                            from jinja2 import Template
+
+                            template = Template(template_content)
+                            content = template.render(**variables)
+                        else:
+                            content = template_content
+                        sys_prompts.append(content)
+                    case LibraryPromptConfig(reference=reference):
+                        try:
+                            content = manifest.prompt_manager.get.sync(reference)
+                            sys_prompts.append(content)
+                        except Exception as e:
+                            msg = f"Failed to load library prompt {reference!r} for agent {name}"
+                            logger.exception(msg)
+                            raise ValueError(msg) from e
+                    case FunctionPromptConfig(function=function, arguments=arguments):
+                        content = function(**arguments)
+                        sys_prompts.append(content)
+
+        # Prepare toolsets list
+        toolsets_list = config.get_toolsets()
+        if config_tool_provider := config.get_tool_provider():
+            toolsets_list.append(config_tool_provider)
+        # Convert workers config to a toolset (backwards compatibility)
+        if config.workers:
+            from agentpool_toolsets.builtin.workers import WorkersTools
+
+            workers_provider = WorkersTools(workers=list(config.workers), name="workers")
+            toolsets_list.append(workers_provider)
+        # Resolve output type
+        agent_output_type = manifest.get_output_type(name) or str
+        resolved_output_type = to_type(agent_output_type, manifest.responses)
+        # Merge event handlers
+        config_handlers = config.get_event_handlers()
+        merged_handlers: list[IndividualEventHandler | BuiltinEventHandlerType] = [
+            *config_handlers,
+            *(event_handlers or []),
+        ]
+        # Resolve model
+        resolved_model = manifest.resolve_model(config.model)
+        model = resolved_model.get_model()
+        model_settings = resolved_model.get_model_settings()
+        # Extract builtin tools
+        builtin_tools = config.get_builtin_tools()
+        return cls(
+            model=model,
+            model_settings=model_settings,
+            system_prompt=sys_prompts,
+            name=name,
+            display_name=config.display_name,
+            deps_type=deps_type,
+            env=config.environment.get_provider() if config.environment else None,
+            description=config.description,
+            retries=config.retries,
+            session=config.get_session_config(),
+            output_retries=config.output_retries,
+            end_strategy=config.end_strategy,
+            agent_config=config,
+            input_provider=input_provider,
+            output_type=resolved_output_type,  # type: ignore[arg-type]
+            event_handlers=merged_handlers or None,
+            agent_pool=agent_pool,
+            tool_mode=config.tool_mode,
+            knowledge=config.knowledge,
+            toolsets=toolsets_list,
+            hooks=config.hooks.get_agent_hooks() if config.hooks else None,
+            tool_confirmation_mode=config.requires_tool_confirmation,
+            builtin_tools=builtin_tools or None,
+            usage_limits=config.usage_limits,
+            providers=config.model_providers,
+        )
+
     async def __aenter__(self) -> Self:
         """Enter async context and set up MCP servers."""
         try:
@@ -379,57 +519,6 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
         """Exit async context."""
         await super().__aexit__(exc_type, exc_val, exc_tb)
 
-    @overload
-    def __and__(  # if other doesnt define deps, we take the agents one
-        self, other: ProcessorCallback[Any] | Team[TDeps] | Agent[TDeps, Any]
-    ) -> Team[TDeps]: ...
-
-    @overload
-    def __and__(  # otherwise, we dont know and deps is Any
-        self, other: ProcessorCallback[Any] | Team[Any] | Agent[Any, Any]
-    ) -> Team[Any]: ...
-
-    def __and__(self, other: MessageNode[Any, Any] | ProcessorCallback[Any]) -> Team[Any]:
-        """Create sequential team using & operator.
-
-        Example:
-            group = analyzer & planner & executor  # Create group of 3
-            group = analyzer & existing_group  # Add to existing group
-        """
-        from agentpool.delegation.team import Team
-
-        match other:
-            case Team():
-                return Team([self, *other.nodes])
-            case Callable():
-                agent_2 = Agent.from_callback(other)
-                agent_2.agent_pool = self.agent_pool
-                return Team([self, agent_2])
-            case MessageNode():
-                return Team([self, other])
-            case _:
-                msg = f"Invalid agent type: {type(other)}"
-                raise ValueError(msg)
-
-    @overload
-    def __or__(self, other: MessageNode[TDeps, Any]) -> TeamRun[TDeps, Any]: ...
-
-    @overload
-    def __or__[TOtherDeps](self, other: MessageNode[TOtherDeps, Any]) -> TeamRun[Any, Any]: ...
-
-    @overload
-    def __or__(self, other: ProcessorCallback[Any]) -> TeamRun[Any, Any]: ...
-
-    def __or__(self, other: MessageNode[Any, Any] | ProcessorCallback[Any]) -> TeamRun[Any, Any]:
-        # Create new execution with sequential mode (for piping)
-        from agentpool import TeamRun
-
-        if callable(other):
-            other = Agent.from_callback(other)
-            other.agent_pool = self.agent_pool
-
-        return TeamRun([self, other])
-
     @overload
     @classmethod
     def from_callback(
@@ -468,16 +557,18 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
             name: Optional name for the agent
             kwargs: Additional arguments for agent
         """
+        from llmling_models import function_to_model
+
         name = name or callback.__name__ or "processor"
         model = function_to_model(callback)
-        return_type = _typing_extra.get_function_type_hints(callback).get("return")
+        output_type = _typing_extra.get_function_type_hints(callback).get("return")
         if (  # If async, unwrap from Awaitable
-            return_type
-            and hasattr(return_type, "__origin__")
-            and return_type.__origin__ is Awaitable
+            output_type
+            and hasattr(output_type, "__origin__")
+            and output_type.__origin__ is Awaitable
         ):
-            return_type = return_type.__args__[0]
-        return Agent(model=model, name=name, output_type=return_type or str, **kwargs)
+            output_type = output_type.__args__[0]
+        return Agent(model=model, name=name, output_type=output_type or str, **kwargs)
 
     @property
     def name(self) -> str:
@@ -509,15 +600,34 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
             data=data,
         )
 
+    def _resolve_model_string(self, model: str) -> tuple[Model, ModelSettings | None]:
+        """Resolve a model string, checking variants first.
+
+        Args:
+            model: Model identifier or variant name
+
+        Returns:
+            Tuple of (Model instance, ModelSettings or None)
+            Settings are only returned for variants.
+        """
+        from llmling_models import infer_model
+
+        # Check if it's a variant
+        if self.agent_pool and model in self.agent_pool.manifest.model_variants:
+            config = self.agent_pool.manifest.model_variants[model]
+            return config.get_model(), config.get_model_settings()
+        # Regular model string - no settings
+        return infer_model(model), None
+
     def to_structured[NewOutputDataT](
         self,
         output_type: type[NewOutputDataT],
-        *,
-        tool_name: str | None = None,
-        tool_description: str | None = None,
     ) -> Agent[TDeps, NewOutputDataT]:
         """Convert this agent to a structured agent.
 
+        Warning: This method mutates the agent in place and breaks caching.
+        Changing output type modifies tool definitions sent to the API.
+
         Args:
             output_type: Type for structured responses. Can be:
                 - A Python type (Pydantic model)
@@ -525,23 +635,17 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
             tool_description: Optional override for result tool description
 
         Returns:
-            Typed Agent
+            Self (same instance, not a copy)
         """
         self.log.debug("Setting result type", output_type=output_type)
         self._output_type = to_type(output_type)  # type: ignore[assignment]
         return self  # type: ignore
 
-    def is_busy(self) -> bool:
-        """Check if agent is currently processing tasks."""
-        return bool(self.task_manager._pending_tasks or self._background_task)
-
     @property
     def model_name(self) -> str | None:
         """Get the model name in a consistent format (provider:model_name)."""
-        if self._model:
-            # Construct full model ID with provider prefix (e.g., "anthropic:claude-haiku-4-5")
-            return f"{self._model.system}:{self._model.model_name}"
-        return None
+        # Construct full model ID with provider prefix (e.g., "anthropic:claude-haiku-4-5")
+        return f"{self._model.system}:{self._model.model_name}" if self._model else None
 
     def to_tool(
         self,
@@ -552,7 +656,7 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
         pass_message_history: bool = False,
         parent: Agent[Any, Any] | None = None,
         **_kwargs: Any,
-    ) -> Tool[OutputDataT]:
+    ) -> FunctionTool[OutputDataT]:
         """Create a tool from this agent.
 
         Args:
@@ -569,7 +673,7 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
                 raise ToolError(msg)
 
             if reset_history_on_run:
-                self.conversation.clear()
+                await self.conversation.clear()
 
             history = None
             if pass_message_history and parent:
@@ -602,8 +706,7 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
 
     async def get_agentlet[AgentOutputType](
         self,
-        tool_choice: str | list[str] | None,
-        model: ModelType,
+        model: ModelType | None,
         output_type: type[AgentOutputType] | None,
         input_provider: InputProvider | None = None,
     ) -> PydanticAgent[TDeps, AgentOutputType]:
@@ -612,10 +715,13 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
 
         from agentpool.agents.tool_wrapping import wrap_tool
 
-        tools = await self.tools.get_tools(state="enabled", names=tool_choice)
+        tools = await self.tools.get_tools(state="enabled")
         final_type = to_type(output_type) if output_type not in [None, str] else self._output_type
         actual_model = model or self._model
-        model_ = infer_model(actual_model) if isinstance(actual_model, str) else actual_model
+        if isinstance(actual_model, str):
+            model_, _settings = self._resolve_model_string(actual_model)
+        else:
+            model_ = actual_model
         agent = PydanticAgent(
             name=self.name,
             model=model_,
@@ -647,162 +753,30 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
 
         return agent  # type: ignore[return-value]
 
-    @overload
-    async def run(
+    async def _stream_events(  # noqa: PLR0915
         self,
-        *prompts: PromptCompatible | ChatMessage[Any],
-        output_type: None = None,
-        model: ModelType = None,
-        store_history: bool = True,
-        tool_choice: str | list[str] | None = None,
-        usage_limits: UsageLimits | None = None,
-        message_id: str | None = None,
-        conversation_id: str | None = None,
-        message_history: MessageHistory | None = None,
-        deps: TDeps | None = None,
-        input_provider: InputProvider | None = None,
-        wait_for_connections: bool | None = None,
-        instructions: str | None = None,
-    ) -> ChatMessage[OutputDataT]: ...
-
-    @overload
-    async def run[OutputTypeT](
-        self,
-        *prompts: PromptCompatible | ChatMessage[Any],
-        output_type: type[OutputTypeT],
-        model: ModelType = None,
-        store_history: bool = True,
-        tool_choice: str | list[str] | None = None,
-        usage_limits: UsageLimits | None = None,
-        message_id: str | None = None,
-        conversation_id: str | None = None,
-        message_history: MessageHistory | None = None,
-        deps: TDeps | None = None,
-        input_provider: InputProvider | None = None,
-        wait_for_connections: bool | None = None,
-        instructions: str | None = None,
-    ) -> ChatMessage[OutputTypeT]: ...
-
-    @method_spawner  # type: ignore[misc]
-    async def run(
-        self,
-        *prompts: PromptCompatible | ChatMessage[Any],
-        output_type: type[Any] | None = None,
-        model: ModelType = None,
-        store_history: bool = True,
-        tool_choice: str | list[str] | None = None,
-        usage_limits: UsageLimits | None = None,
-        message_id: str | None = None,
-        conversation_id: str | None = None,
-        message_history: MessageHistory | None = None,
-        deps: TDeps | None = None,
-        input_provider: InputProvider | None = None,
-        wait_for_connections: bool | None = None,
-        instructions: str | None = None,
-    ) -> ChatMessage[Any]:
-        """Run agent with prompt and get response.
-
-        Args:
-            prompts: User query or instruction
-            output_type: Optional type for structured responses
-            model: Optional model override
-            store_history: Whether the message exchange should be added to the
-                            context window
-            tool_choice: Filter tool choice by name
-            usage_limits: Optional usage limits for the model
-            message_id: Optional message id for the returned message.
-                        Automatically generated if not provided.
-            conversation_id: Optional conversation id for the returned message.
-            message_history: Optional MessageHistory object to
-                             use instead of agent's own conversation
-            deps: Optional dependencies for the agent
-            input_provider: Optional input provider for the agent
-            wait_for_connections: Whether to wait for connected agents to complete
-            instructions: Optional instructions to override the agent's system prompt
-
-        Returns:
-            Result containing response and run information
-
-        Raises:
-            UnexpectedModelBehavior: If the model fails or behaves unexpectedly
-        """
-        # Collect all events through run_stream
-        final_message: ChatMessage[Any] | None = None
-        async for event in self.run_stream(
-            *prompts,
-            output_type=output_type,
-            model=model,
-            store_history=store_history,
-            tool_choice=tool_choice,
-            usage_limits=usage_limits,
-            message_id=message_id,
-            conversation_id=conversation_id,
-            message_history=message_history,
-            deps=deps,
-            input_provider=input_provider,
-            wait_for_connections=wait_for_connections,
-            instructions=instructions,
-        ):
-            if isinstance(event, StreamCompleteEvent):
-                final_message = event.message
-
-        if final_message is None:
-            msg = "No final message received from stream"
-            raise RuntimeError(msg)
-
-        return final_message
-
-    @method_spawner
-    async def run_stream(  # noqa: PLR0915
-        self,
-        *prompt: PromptCompatible,
-        output_type: type[OutputDataT] | None = None,
-        model: ModelType = None,
-        tool_choice: str | list[str] | None = None,
+        prompts: list[UserContent],
+        *,
+        user_msg: ChatMessage[Any],
+        effective_parent_id: str | None,
         store_history: bool = True,
-        usage_limits: UsageLimits | None = None,
         message_id: str | None = None,
         conversation_id: str | None = None,
+        parent_id: str | None = None,
         message_history: MessageHistory | None = None,
         input_provider: InputProvider | None = None,
         wait_for_connections: bool | None = None,
         deps: TDeps | None = None,
-        instructions: str | None = None,
         event_handlers: Sequence[IndividualEventHandler | BuiltinEventHandlerType] | None = None,
     ) -> AsyncIterator[RichAgentStreamEvent[OutputDataT]]:
-        """Run agent with prompt and get a streaming response.
-
-        Args:
-            prompt: User query or instruction
-            output_type: Optional type for structured responses
-            model: Optional model override
-            tool_choice: Filter tool choice by name
-            store_history: Whether the message exchange should be added to the
-                           context window
-            usage_limits: Optional usage limits for the model
-            message_id: Optional message id for the returned message.
-                        Automatically generated if not provided.
-            conversation_id: Optional conversation id for the returned message.
-            message_history: Optional MessageHistory to use instead of agent's own
-            input_provider: Optional input provider for the agent
-            wait_for_connections: Whether to wait for connected agents to complete
-            deps: Optional dependencies for the agent
-            instructions: Optional instructions to override the agent's system prompt
-            event_handlers: Optional event handlers for this run (overrides agent's handlers)
+        from anyenv import MultiEventHandler
+        from pydantic_graph import End
 
-        Returns:
-            An async iterator yielding streaming events with final message embedded.
+        from agentpool.agents.events import resolve_event_handlers
 
-        Raises:
-            UnexpectedModelBehavior: If the model fails or behaves unexpectedly
-        """
         conversation = message_history if message_history is not None else self.conversation
         # Use provided event handlers or fall back to agent's handlers
         if event_handlers is not None:
-            from anyenv import MultiEventHandler
-
-            from agentpool.agents.events import resolve_event_handlers
-
             handler: MultiEventHandler[IndividualEventHandler] = MultiEventHandler(
                 resolve_event_handlers(event_handlers)
             )
@@ -810,18 +784,15 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
             handler = self.event_handler
         message_id = message_id or str(uuid4())
         run_id = str(uuid4())
-        # Get parent_id from last message in history for tree structure
-        last_msg_id = conversation.get_last_message_id()
-        user_msg, prompts, original_message = await prepare_prompts(*prompt, parent_id=last_msg_id)
-        self.message_received.emit(user_msg)
+        # Reset cancellation state
+        self._cancelled = False
+        # Initialize conversation_id on first run and log to storage
+        # Conversation ID initialization handled by BaseAgent
+        processed_prompts = prompts
+        await self.message_received.emit(user_msg)
         start_time = time.perf_counter()
         history_list = conversation.get_history()
         pending_parts = conversation.get_pending_parts()
-
-        # Reset cancellation state and track current task
-        self._cancelled = False
-        self._current_stream_task = asyncio.current_task()
-
         # Execute pre-run hooks
         if self.hooks:
             pre_run_result = await self.hooks.run_pre_run_hooks(
@@ -829,159 +800,132 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
                 prompt=user_msg.content
                 if isinstance(user_msg.content, str)
                 else str(user_msg.content),
-                conversation_id=conversation_id,
+                conversation_id=self.conversation_id,
             )
             if pre_run_result.get("decision") == "deny":
                 reason = pre_run_result.get("reason", "Blocked by pre-run hook")
                 msg = f"Run blocked: {reason}"
                 raise RuntimeError(msg)
 
+        assert self.conversation_id is not None  # Initialized by BaseAgent.run_stream()
         run_started = RunStartedEvent(
             thread_id=self.conversation_id, run_id=run_id, agent_name=self.name
         )
         await handler(None, run_started)
         yield run_started
-        try:
-            from pydantic_graph import End
-
-            agentlet = await self.get_agentlet(tool_choice, model, output_type, input_provider)
-            content = await convert_prompts(prompts)
-            response_msg: ChatMessage[Any] | None = None
-            # Prepend pending context parts (content is already pydantic-ai format)
-            converted = [*pending_parts, *content]
-
-            # Use provided usage_limits or fall back to default
-            effective_limits = usage_limits or self._default_usage_limits
-            history = [m for run in history_list for m in run.to_pydantic_ai()]
-
-            # Track tool call starts to combine with results later
-            pending_tcs: dict[str, BaseToolCallPart] = {}
-            file_tracker = FileTracker()
-
-            async with agentlet.iter(
-                converted,
-                deps=deps,  # type: ignore[arg-type]
-                message_history=history,
-                usage_limits=effective_limits,
-                instructions=instructions,
-            ) as agent_run:
-                try:
-                    async for node in agent_run:
-                        if self._cancelled:
-                            self.log.info("Stream cancelled by user")
-                            break
-                        if isinstance(node, End):
-                            break
-
-                        # Stream events from model request node
-                        if isinstance(node, ModelRequestNode):
-                            async with (
-                                node.stream(agent_run.ctx) as agent_stream,
-                                merge_queue_into_iterator(
-                                    agent_stream,  # type: ignore[arg-type]
-                                    self._event_queue,
-                                ) as merged,
-                            ):
-                                async for event in file_tracker.track(merged):
-                                    if self._cancelled:
-                                        break
-                                    await handler(None, event)
-                                    yield event
-                                    combined = self._process_tool_event(
-                                        event, pending_tcs, message_id
-                                    )
-                                    if combined:
-                                        await handler(None, combined)
-                                        yield combined
-
-                        # Stream events from tool call node
-                        elif isinstance(node, CallToolsNode):
-                            async with (
-                                node.stream(agent_run.ctx) as tool_stream,
-                                merge_queue_into_iterator(tool_stream, self._event_queue) as merged,
-                            ):
-                                async for event in file_tracker.track(merged):
-                                    if self._cancelled:
-                                        break
-                                    await handler(None, event)
-                                    yield event
-                                    combined = self._process_tool_event(
-                                        event, pending_tcs, message_id
-                                    )
-                                    if combined:
-                                        await handler(None, combined)
-                                        yield combined
-                except asyncio.CancelledError:
-                    self.log.info("Stream cancelled via task cancellation")
-                    self._cancelled = True
-
-                # Build response message
-                response_time = time.perf_counter() - start_time
-                if self._cancelled:
-                    partial_content = _extract_text_from_messages(
-                        agent_run.all_messages(), include_interruption_note=True
-                    )
-                    response_msg = ChatMessage(
-                        content=partial_content,
-                        role="assistant",
-                        name=self.name,
-                        message_id=message_id,
-                        conversation_id=conversation_id or user_msg.conversation_id,
-                        parent_id=user_msg.message_id,
-                        response_time=response_time,
-                        finish_reason="stop",
-                    )
-                    complete_event = StreamCompleteEvent(message=response_msg)
-                    await handler(None, complete_event)
-                    yield complete_event
-                    self._current_stream_task = None
-                    return
-
-                if agent_run.result:
-                    response_msg = await ChatMessage.from_run_result(
-                        agent_run.result,
-                        agent_name=self.name,
-                        message_id=message_id,
-                        conversation_id=conversation_id or user_msg.conversation_id,
-                        parent_id=user_msg.message_id,
-                        response_time=response_time,
-                        metadata=file_tracker.get_metadata(),
-                    )
-                else:
-                    msg = "Stream completed without producing a result"
-                    raise RuntimeError(msg)  # noqa: TRY301
 
-            # Execute post-run hooks
-            if self.hooks:
-                prompt_str = (
-                    user_msg.content if isinstance(user_msg.content, str) else str(user_msg.content)
+        agentlet = await self.get_agentlet(None, self._output_type, input_provider)
+        content = await convert_prompts(processed_prompts)
+        response_msg: ChatMessage[Any] | None = None
+        # Prepend pending context parts (content is already pydantic-ai format)
+        converted = [*pending_parts, *content]
+        history = [m for run in history_list for m in run.to_pydantic_ai()]
+        # Track tool call starts to combine with results later
+        pending_tcs: dict[str, BaseToolCallPart] = {}
+        file_tracker = FileTracker()
+        async with agentlet.iter(
+            converted,
+            deps=deps,  # type: ignore[arg-type]
+            message_history=history,
+            usage_limits=self._default_usage_limits,
+        ) as agent_run:
+            try:
+                async for node in agent_run:
+                    if self._cancelled:
+                        self.log.info("Stream cancelled by user")
+                        break
+                    if isinstance(node, End):
+                        break
+
+                    # Stream events from model request node
+                    if isinstance(node, ModelRequestNode):
+                        async with (
+                            node.stream(agent_run.ctx) as agent_stream,
+                            merge_queue_into_iterator(
+                                agent_stream,  # type: ignore[arg-type]
+                                self._event_queue,
+                            ) as merged,
+                        ):
+                            async for event in file_tracker(merged):
+                                if self._cancelled:
+                                    break
+                                await handler(None, event)
+                                yield event
+                                combined = self._process_tool_event(event, pending_tcs, message_id)
+                                if combined:
+                                    await handler(None, combined)
+                                    yield combined
+
+                    # Stream events from tool call node
+                    elif isinstance(node, CallToolsNode):
+                        async with (
+                            node.stream(agent_run.ctx) as tool_stream,
+                            merge_queue_into_iterator(tool_stream, self._event_queue) as merged,
+                        ):
+                            async for event in file_tracker(merged):
+                                if self._cancelled:
+                                    break
+                                await handler(None, event)
+                                yield event
+                                combined = self._process_tool_event(event, pending_tcs, message_id)
+                                if combined:
+                                    await handler(None, combined)
+                                    yield combined
+            except asyncio.CancelledError:
+                self.log.info("Stream cancelled via task cancellation")
+                self._cancelled = True
+
+            # Build response message
+            response_time = time.perf_counter() - start_time
+            if self._cancelled:
+                partial_content = _extract_text_from_messages(
+                    agent_run.all_messages(), include_interruption_note=True
+                )
+                response_msg = ChatMessage(
+                    content=partial_content,
+                    role="assistant",
+                    name=self.name,
+                    message_id=message_id,
+                    conversation_id=self.conversation_id,
+                    parent_id=user_msg.message_id,
+                    response_time=response_time,
+                    finish_reason="stop",
                 )
-                await self.hooks.run_post_run_hooks(
+                complete_event = StreamCompleteEvent(message=response_msg)
+                await handler(None, complete_event)
+                yield complete_event
+                return
+
+            if agent_run.result:
+                response_msg = await ChatMessage.from_run_result(
+                    agent_run.result,
                     agent_name=self.name,
-                    prompt=prompt_str,
-                    result=response_msg.content,
-                    conversation_id=conversation_id,
+                    message_id=message_id,
+                    conversation_id=self.conversation_id,
+                    parent_id=user_msg.message_id,
+                    response_time=response_time,
+                    metadata=file_tracker.get_metadata(),
                 )
+            else:
+                msg = "Stream completed without producing a result"
+                raise RuntimeError(msg)
 
-            # Apply forwarding logic if needed
-            if original_message:
-                response_msg = response_msg.forwarded(original_message)
-            # Send additional enriched completion event
-            complete_event = StreamCompleteEvent(message=response_msg)
-            await handler(None, complete_event)
-            yield complete_event
-            self.message_sent.emit(response_msg)
-            await self.log_message(response_msg)
-            if store_history:
-                conversation.add_chat_messages([user_msg, response_msg])
-            await self.connections.route_message(response_msg, wait=wait_for_connections)
+        # Execute post-run hooks
+        if self.hooks:
+            prompt_str = (
+                user_msg.content if isinstance(user_msg.content, str) else str(user_msg.content)
+            )
+            await self.hooks.run_post_run_hooks(
+                agent_name=self.name,
+                prompt=prompt_str,
+                result=response_msg.content,
+                conversation_id=self.conversation_id,
+            )
 
-        except Exception as e:
-            self.log.exception("Agent stream failed")
-            self.run_failed.emit("Agent stream failed", e)
-            raise
-        finally:
-            self._current_stream_task = None
+        # Send additional enriched completion event
+        complete_event = StreamCompleteEvent(message=response_msg)
+        await handler(None, complete_event)
+        yield complete_event
 
     def _process_tool_event(
         self,
@@ -1018,45 +962,6 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
                     )
         return None
 
-    async def run_iter(
-        self,
-        *prompt_groups: Sequence[PromptCompatible],
-        output_type: type[OutputDataT] | None = None,
-        model: ModelType = None,
-        store_history: bool = True,
-        wait_for_connections: bool | None = None,
-    ) -> AsyncIterator[ChatMessage[OutputDataT]]:
-        """Run agent sequentially on multiple prompt groups.
-
-        Args:
-            prompt_groups: Groups of prompts to process sequentially
-            output_type: Optional type for structured responses
-            model: Optional model override
-            store_history: Whether to store in conversation history
-            wait_for_connections: Whether to wait for connected agents
-
-        Yields:
-            Response messages in sequence
-
-        Example:
-            questions = [
-                ["What is your name?"],
-                ["How old are you?", image1],
-                ["Describe this image", image2],
-            ]
-            async for response in agent.run_iter(*questions):
-                print(response.content)
-        """
-        for prompts in prompt_groups:
-            response = await self.run(
-                *prompts,
-                output_type=output_type,
-                model=model,
-                store_history=store_history,
-                wait_for_connections=wait_for_connections,
-            )
-            yield response  # pyright: ignore
-
     @method_spawner
     async def run_job(
         self,
@@ -1109,122 +1014,6 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
             msg = f"Task execution failed: {e}"
             raise JobError(msg) from e
 
-    async def run_in_background(
-        self,
-        *prompt: PromptCompatible,
-        max_count: int | None = None,
-        interval: float = 1.0,
-        **kwargs: Any,
-    ) -> asyncio.Task[ChatMessage[OutputDataT] | None]:
-        """Run agent continuously in background with prompt or dynamic prompt function.
-
-        Args:
-            prompt: Static prompt or function that generates prompts
-            max_count: Maximum number of runs (None = infinite)
-            interval: Seconds between runs
-            **kwargs: Arguments passed to run()
-        """
-        self._infinite = max_count is None
-
-        async def _continuous() -> ChatMessage[Any]:
-            count = 0
-            self.log.debug("Starting continuous run", max_count=max_count, interval=interval)
-            latest = None
-            while (max_count is None or count < max_count) and not self._cancelled:
-                try:
-                    agent_ctx = self.get_context()
-                    current_prompts = [
-                        call_with_context(p, agent_ctx, **kwargs) if callable(p) else p
-                        for p in prompt
-                    ]
-                    self.log.debug("Generated prompt", iteration=count)
-                    latest = await self.run(current_prompts, **kwargs)
-                    self.log.debug("Run continuous result", iteration=count)
-
-                    count += 1
-                    await anyio.sleep(interval)
-                except asyncio.CancelledError:
-                    self.log.debug("Continuous run cancelled")
-                    break
-                except Exception:
-                    # Check if we were cancelled (may surface as other exceptions)
-                    if self._cancelled:
-                        self.log.debug("Continuous run cancelled via flag")
-                        break
-                    count += 1
-                    self.log.exception("Background run failed")
-                    await anyio.sleep(interval)
-            self.log.debug("Continuous run completed", iterations=count)
-            return latest  # type: ignore[return-value]
-
-        await self.stop()  # Cancel any existing background task
-        self._cancelled = False  # Reset cancellation flag for new run
-        task = asyncio.create_task(_continuous(), name=f"background_{self.name}")
-        self.log.debug("Started background task", task_name=task.get_name())
-        self._background_task = task
-        return task
-
-    async def stop(self) -> None:
-        """Stop continuous execution if running."""
-        self._cancelled = True  # Signal cancellation via flag
-        if self._background_task and not self._background_task.done():
-            self._background_task.cancel()
-            with suppress(asyncio.CancelledError):  # Expected when we cancel the task
-                await self._background_task
-            self._background_task = None
-
-    async def wait(self) -> ChatMessage[OutputDataT]:
-        """Wait for background execution to complete."""
-        if not self._background_task:
-            msg = "No background task running"
-            raise RuntimeError(msg)
-        if self._infinite:
-            msg = "Cannot wait on infinite execution"
-            raise RuntimeError(msg)
-        try:
-            return await self._background_task
-        finally:
-            self._background_task = None
-
-    async def share(
-        self,
-        target: Agent[TDeps, Any],
-        *,
-        tools: list[str] | None = None,
-        history: bool | int | None = None,  # bool or number of messages
-        token_limit: int | None = None,
-    ) -> None:
-        """Share capabilities and knowledge with another agent.
-
-        Args:
-            target: Agent to share with
-            tools: List of tool names to share
-            history: Share conversation history:
-                    - True: Share full history
-                    - int: Number of most recent messages to share
-                    - None: Don't share history
-            token_limit: Optional max tokens for history
-
-        Raises:
-            ValueError: If requested items don't exist
-            RuntimeError: If runtime not available for resources
-        """
-        # Share tools if requested
-        for name in tools or []:
-            tool = await self.tools.get_tool(name)
-            meta = {"shared_from": self.name}
-            target.tools.register_tool(tool.callable, metadata=meta)
-
-        # Share history if requested
-        if history:
-            history_text = await self.conversation.format_history(
-                max_tokens=token_limit,
-                num_messages=history if isinstance(history, int) else None,
-            )
-            target.conversation.add_context_message(
-                history_text, source=self.name, metadata={"type": "shared_history"}
-            )
-
     def register_worker(
         self,
         worker: MessageNode[Any, Any],
@@ -1242,14 +1031,19 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
             parent=self if pass_message_history else None,
         )
 
-    async def set_model(self, model: ModelType) -> None:
+    async def set_model(self, model: Model | str) -> None:
         """Set the model for this agent.
 
         Args:
             model: New model to use (name or instance)
 
         """
-        self._model = infer_model(model) if isinstance(model, str) else model
+        if isinstance(model, str):
+            self._model, settings = self._resolve_model_string(model)
+            if settings:
+                self.model_settings = settings
+        else:
+            self._model = model
 
     async def set_tool_confirmation_mode(self, mode: ToolConfirmationMode) -> None:
         """Set the tool confirmation mode for this agent.
@@ -1263,20 +1057,6 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
         self.tool_confirmation_mode = mode
         self.log.info("Tool confirmation mode changed", mode=mode)
 
-    async def reset(self) -> None:
-        """Reset agent state (conversation history and tool states)."""
-        old_tools = await self.tools.list_tools()
-        self.conversation.clear()
-        await self.tools.reset_states()
-        new_tools = await self.tools.list_tools()
-
-        event = self.AgentReset(
-            agent_name=self.name,
-            previous_tools=old_tools,
-            new_tools=new_tools,
-        )
-        self.agent_reset.emit(event)
-
     @asynccontextmanager
     async def temporary_state[T](
         self,
@@ -1305,6 +1085,7 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
             model: Temporary model override
         """
         old_model = self._model
+        old_settings = self.model_settings
         if output_type:
             old_type = self._output_type
             self.to_structured(output_type)
@@ -1327,14 +1108,21 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
             if pause_routing:  # Routing
                 await stack.enter_async_context(self.connections.paused_routing())
 
-            elif model is not None:  # Model
-                self._model = infer_model(model) if isinstance(model, str) else model
+            if model is not None:  # Model
+                if isinstance(model, str):
+                    self._model, settings = self._resolve_model_string(model)
+                    if settings:
+                        self.model_settings = settings
+                else:
+                    self._model = model
 
             try:
                 yield self
-            finally:  # Restore model
-                if model is not None and old_model:
-                    self._model = old_model
+            finally:  # Restore model and settings
+                if model is not None:
+                    if old_model:
+                        self._model = old_model
+                    self.model_settings = old_settings
                 if output_type:
                     self.to_structured(old_type)
 
@@ -1375,17 +1163,19 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
             self.log.exception("Failed to discover models")
             return None
 
-    def get_modes(self) -> list[ModeCategory]:
+    async def get_modes(self) -> list[ModeCategory]:
         """Get available mode categories for this agent.
 
-        Native agents expose tool confirmation modes.
+        Native agents expose permission modes and model selection.
 
         Returns:
-            List with single ModeCategory for tool confirmation
+            List of ModeCategory for permissions and models
         """
         from agentpool.agents.modes import ModeCategory, ModeInfo
 
-        # Map current confirmation mode to mode ID
+        categories: list[ModeCategory] = []
+
+        # Permission modes
         mode_id_map = {
             "per_tool": "default",
             "always": "default",
@@ -1393,67 +1183,105 @@ class Agent[TDeps = None, OutputDataT = str](BaseAgent[TDeps, OutputDataT]):
         }
         current_id = mode_id_map.get(self.tool_confirmation_mode, "default")
 
-        category_id = "permissions"
-        return [
+        categories.append(
             ModeCategory(
-                id=category_id,
+                id="permissions",
                 name="Permissions",
                 available_modes=[
                     ModeInfo(
                         id="default",
                         name="Default",
                         description="Require confirmation for tools marked as needing it",
-                        category_id=category_id,
+                        category_id="permissions",
                     ),
                     ModeInfo(
                         id="acceptEdits",
                         name="Accept Edits",
                         description="Auto-approve all tool calls without confirmation",
-                        category_id=category_id,
+                        category_id="permissions",
                     ),
                 ],
                 current_mode_id=current_id,
+                category="mode",
             )
-        ]
+        )
+
+        # Model selection
+        models = await self.get_available_models()
+        if models:
+            current_model = self.model_name or (models[0].id if models else "")
+            categories.append(
+                ModeCategory(
+                    id="model",
+                    name="Model",
+                    available_modes=[
+                        ModeInfo(
+                            id=m.id,
+                            name=m.name or m.id,
+                            description=m.description or "",
+                            category_id="model",
+                        )
+                        for m in models
+                    ],
+                    current_mode_id=current_model,
+                    category="model",
+                )
+            )
+
+        return categories
 
     async def set_mode(self, mode: ModeInfo | str, category_id: str | None = None) -> None:
         """Set a mode for this agent.
 
-        Native agents support the "permissions" category with modes:
-        - "default": per_tool confirmation
-        - "acceptEdits": never confirm (auto-approve)
+        Native agents support:
+        - "permissions" category: default, acceptEdits
+        - "model" category: any available model ID
 
         Args:
             mode: Mode to activate - ModeInfo object or mode ID string
-            category_id: Optional category (only "permissions" supported)
+            category_id: Category ID ("permissions" or "model")
 
         Raises:
-            ValueError: If mode_id is invalid
+            ValueError: If mode_id or category_id is invalid
         """
         # Extract mode_id and category from ModeInfo if provided
         if isinstance(mode, ModeInfo):
             mode_id = mode.id
-            category_id = category_id or mode.category_id or None
+            category_id = category_id or mode.category_id
         else:
             mode_id = mode
 
-        # Validate category if provided
-        if category_id is not None and category_id != "permissions":
-            msg = f"Unknown category: {category_id}. Only 'permissions' is supported."
-            raise ValueError(msg)
-
-        # Map mode_id to confirmation mode
-        mode_map: dict[str, ToolConfirmationMode] = {
-            "default": "per_tool",
-            "acceptEdits": "never",
-        }
+        # Default to permissions if no category specified
+        if category_id is None:
+            category_id = "permissions"
+
+        if category_id == "permissions":
+            # Map mode_id to confirmation mode
+            mode_map: dict[str, ToolConfirmationMode] = {
+                "default": "per_tool",
+                "acceptEdits": "never",
+            }
+            if mode_id not in mode_map:
+                msg = f"Unknown permission mode: {mode_id}. Available: {list(mode_map.keys())}"
+                raise ValueError(msg)
+            await self.set_tool_confirmation_mode(mode_map[mode_id])
+
+        elif category_id == "model":
+            # Validate model exists
+            models = await self.get_available_models()
+            if models:
+                valid_ids = {m.id for m in models}
+                if mode_id not in valid_ids:
+                    msg = f"Unknown model: {mode_id}. Available: {valid_ids}"
+                    raise ValueError(msg)
+            # Set the model using set_model method
+            await self.set_model(mode_id)
+            self.log.info("Model changed", model=mode_id)
 
-        if mode_id not in mode_map:
-            msg = f"Unknown mode: {mode_id}. Available: {list(mode_map.keys())}"
+        else:
+            msg = f"Unknown category: {category_id}. Available: permissions, model"
             raise ValueError(msg)
 
-        await self.set_tool_confirmation_mode(mode_map[mode_id])
-
 
 if __name__ == "__main__":
     import logging
@@ -1468,4 +1296,4 @@ if __name__ == "__main__":
         print(f"[EVENT] {type(event).__name__}: {event}")
 
     agent = Agent(model=_model, tools=["webbrowser.open"], event_handlers=[handle_events])
-    result = agent.run.sync(sys_prompt)  # type: ignore[attr-defined]
+    result = agent.run.sync(sys_prompt)