Agent Class API

class BaseAgent(ABC):
    def __init__(
        self,
        model: Union[BaseVLM, BaseLLM, BaseAPIModel],
        name: str,
        goal: str,
        instruction: str,
        tools: Optional[Dict[str, Callable]] = None,
        max_tokens: Optional[int] = 10000,
        allowed_peers: Optional[List[str]] = None,
        bidirectional_peers: bool = False,
        is_convergence_point: Optional[bool] = None,
        input_schema: Optional[Any] = None,
        output_schema: Optional[Any] = None,
        memory_retention: str = "session",
        memory_storage_path: Optional[str] = None
    )

@abstractmethod
async def _run(
    self,
    prompt: Any,
    context: Dict[str, Any],
    **kwargs
) -> Message:
    """
    Pure execution logic - must be implemented by subclasses.
    This method must be pure - no side effects allowed!
    """
    pass

async def run(
    self,
    prompt: Union[str, Message, Dict],
    context: Optional[Dict[str, Any]] = None,
    **kwargs
) -> Message:
    """Execute agent with automatic context management."""

async def cleanup(self) -> None:
    """
    Clean up agent resources.
    Called automatically by Orchestra after run completes.
    """

from marsys.agents import Agent
from marsys.models import ModelConfig

agent = Agent(
    model_config=ModelConfig(
        type="api",
        provider="openrouter",
        name="anthropic/claude-haiku-4.5",
        max_tokens=12000
    ),
    name="Assistant",
    goal="A helpful assistant that answers questions",
    instruction="You are a helpful assistant. Respond clearly and concisely.",
    tools={"search": search_function},
    allowed_peers=["Researcher", "Writer"]
)

from marsys.agents import BrowserAgent

browser = await BrowserAgent.create_safe(
    model_config=config,
    name="WebScraper",
    mode="primitive",  # or "advanced"
    goal="Extract data from websites",
    instruction="You are a web scraping specialist. Navigate to websites, extract requested data, and return structured results.",
    headless=True,
    tmp_dir="./tmp/browser"
)

try:
    result = await browser.run("Go to example.com and extract headings")
finally:
    await browser.cleanup()

from marsys.agents.agent_pool import AgentPool

pool = AgentPool(
    agent_template=agent,
    pool_size=5
)

# Acquire agent for use
async with pool.acquire(branch_id="branch_1") as agent:
    result = await agent.run(task)

# Manual cleanup
agent = Agent(
    name="my_agent",
    model_config=config,
    goal="Process data efficiently",
    instruction="You are a data processing agent. Handle data operations as requested."
)
result = await agent.run("Process data")
await agent.cleanup()

# Unregister from registry
from marsys.agents.registry import AgentRegistry
AgentRegistry.unregister_if_same("my_agent", agent)