Source code for sim_platform.agents.carrier.agent

"""A small task-oriented trading Agent; scheduling and transport live outside it."""

from __future__ import annotations

from typing import TYPE_CHECKING, Any, Dict, Iterable, Optional, Sequence, Tuple, Union

from sim_platform.domain.models import ContractError
from sim_platform.agents.tools.protocol.errors import ToolError
from sim_platform.agents.tools.client.base import PlatformTool
from sim_platform.agents.tools.client.collection import TOOL_TYPES
from .conversation import Conversation
from .task import Task

if TYPE_CHECKING:  # Annotation only.
    from sim_platform.agents.tools.client.base import Tool
    from sim_platform.sdk.context import AgentModel
    from .model import ToolCall


def tool_error(code: str, message: str) -> Dict[str, Any]:
    """A tool result in the platform's error shape, for errors raised before a tool ran."""
    return dict(status='error', error=dict(code=code, message=message))


[docs] class TradingAgent: """Run a task using a model and callable Tool objects, retaining this run's history. Construct this once for an experiment, then call run(task) for each scheduled task. Tools own their interfaces; the model adapter owns provider formatting. The Agent only performs the model -> tools -> model loop. An ordinary text reply does not finish a task: a successful completion Tool must end it. ``label`` names the role (for example 'news analyst'); evaluations report model calls and tokens per label. ``finish_tools`` names local tools whose call also ends the task, returning that tool's result. Use it for a role inside a larger Agent, such as an analyst that ends by submitting a report, so the role never needs the platform's finish or wait. """ def __init__( self, model: AgentModel, tools: Iterable[Tool], instructions: str, parameters: Optional[Dict[str, Any]] = None, finish_tools: Iterable[str] = (), label: Optional[str] = None, ) -> None: self.model = model tools = tuple(tools) self.tools = {tool.function_name: tool for tool in tools} if len(self.tools) != len(tools): raise ContractError('agent tools must have distinct names') reserved = {name.replace('.', '_') for name in TOOL_TYPES} if any( tool.function_name in reserved and not isinstance(tool, PlatformTool) for tool in tools ): raise ContractError('local tools cannot replace platform tool names') self.conversation = Conversation(instructions, parameters or {}) if label is not None and ( not isinstance(label, str) or not 0 < len(label) <= 64 or not label.isprintable() ): raise ContractError('label must be printable text of at most 64 characters') self.conversation.label = label self.finish_tools = frozenset(name.replace('.', '_') for name in finish_tools) unknown = self.finish_tools - { name for name, tool in self.tools.items() if not isinstance(tool, PlatformTool) } if unknown: raise ContractError('finish_tools must name local tools given to this agent') def _execute(self, call: ToolCall) -> Tuple[Any, bool]: """Run one tool call; return its result and whether it ended the task.""" tool = self.tools.get(call.name) if tool is None: return tool_error('TOOL_UNAVAILABLE', 'tool is not available to this agent'), False try: result = tool.invoke(call.arguments()) except ToolError as error: return tool_error(error.code, str(error)), False # An uncertain transport error propagates; the Agent never retries a trade. if call.name in self.finish_tools: return result, True return ( result, isinstance(tool, PlatformTool) and tool.ends_work and result.get('status') == 'ok', ) def _mixed_completion(self, calls: Sequence[ToolCall]) -> bool: """Whether a finish/wait tool was requested together with other calls.""" return len(calls) > 1 and any( call.name in self.finish_tools or ( isinstance(self.tools.get(call.name), PlatformTool) and self.tools[call.name].ends_work ) for call in calls )
[docs] def run(self, task: Union[str, Task]) -> dict: """Perform a task until finish/wait succeeds, returning that completion result. Pass a string for a direct task, or Task to include a scheduler notification. Context is retained between calls on this Agent. Each tool result is appended before asking the model again; zero trades is a valid completed task. """ task = Task(task) if isinstance(task, str) else task if not isinstance(task, Task): raise ContractError('agent.run requires task text or a Task') self.conversation.start_task(task) while True: calls = self.model.respond(self.conversation, list(self.tools.values())) if not calls: self.conversation.continue_work() continue mixed = self._mixed_completion(calls) for call in calls: if mixed: result = tool_error('INVALID_ARGUMENT', 'finish and wait must be called alone') finished = False else: result, finished = self._execute(call) self.conversation.tool_result(call, result) if finished: return result