Agent Types¶

Overview¶

codemol provides 7 specialist agents, each with domain-specific prompts and tool group filters. A router automatically selects the right agent(s) for each request.

Registered Agents¶

Agent	Description	Tool Groups
`general`	Default molecular biology assistant	All tools
`trajectory`	MD simulation analysis	trajectory, analysis, representations
`docking`	GOLD docking analysis	docking, interactions, representations
`report`	Scientific report writer	All tools (read-only focus)
`structure`	Structural analysis	analysis, measurements, representations
`interaction`	Interaction analysis	interactions, measurements, labels
`visualization`	Figure preparation	representations, color, labels, rendering, camera

Agent Definition¶

Each agent is an AgentType dataclass in agents/registry.py:

@dataclass
class AgentType:
    name: str
    description: str
    system_prompt: str
    default_model: str | None = None
    tool_groups: list[str] | None = None  # None = all tools
    max_tool_rounds: int = 5

Tool Group Filtering¶

When tool_groups is set, the agent only sees schemas for those groups. For example, the trajectory agent can only call trajectory, analysis, and representation tools — it can't accidentally load new structures or modify labels.

The Router¶

agents/router.py classifies user requests and creates execution plans:

graph TD
    A[User request] --> B[Router Agent]
    B -->|fast model| C{Classify}
    C --> D["[{agent: docking, task: analyze}]"]
    C --> E["[{agent: general, task: help}]"]
    C --> F["[{agent: docking, task: analyze},<br/>{agent: report, task: write report}]"]

Single Agent¶

User: "show hydrogen bonds"
Router: [{"agent": "interaction", "task": "show hydrogen bonds"}]

Pipeline (Multi-Agent)¶

User: "analyze the docking and write a report"
Router: [
    {"agent": "docking", "task": "analyze the docking results"},
    {"agent": "report", "task": "write a report based on the analysis"}
]

Each agent's output is passed as context to the next agent in the pipeline.

Router Model¶

The router uses a fast/cheap model (default: gpt-4o-mini) since it only needs to classify — not reason deeply. Configured via ROUTER_MODEL env variable.

Using Agents¶

Commands¶

/agents list              # Show available agent types
/agents use general       # Start conversation with general agent
/agents use trajectory    # Switch to trajectory specialist
/agents stop              # End agent session
/agents status            # Show current agent state
/agents config model X    # Override model

Natural Language¶

Once an agent is active, type without the / prefix:

> show me the binding site of the ligand
Agent: I'll highlight the binding site...
[calls /selection nearby organic, /rep sticks _nearby, /color bychain _nearby]