Create Agent

Follow this checklist when creating a new agent. Replace <name> with the agent name (lowercase, e.g. reviewer) and <Name> with the PascalCase class name (e.g. ReviewerAgent).

Progress:
- [ ] Step 1: Create directory structure
- [ ] Step 2: Write SKILL.md
- [ ] Step 3: Write agent.py
- [ ] Step 4: Write package __init__.py
- [ ] Step 5: Register in src/agents/__init__.py
- [ ] Step 6: Add to workflow graph
- [ ] Step 7: Update router
- [ ] Step 8: Run verification

Step 1: Create directory structure

src/agents/<name>/
├── __init__.py
├── agent.py
└── skills/
    └── <skill_name>/
        ├── SKILL.md
        └── tools/          # optional, only if agent needs tools
            ├── __init__.py
            └── <tool>.py

Step 2: Write SKILL.md

Create src/agents/<name>/skills/<skill_name>/SKILL.md:

markdown
1---
2name: <skill_name>
3description: Brief description of what this skill does
4tags: [<tag1>, <tag2>]
5---
6
7# <Skill Title>
8
9Detailed instructions the LLM follows when this skill is loaded...

Step 3: Write agent.py

Create src/agents/<name>/agent.py following this skeleton:

python
1"""
2<Name> Agent - <one-line purpose>
3"""
4
5from pathlib import Path
6
7from langchain_core.messages import BaseMessage, AIMessage
8
9from ..base import BaseAgent
10from ...skills.registry import SkillRegistry
11from ...skills.loader import SkillLoader
12
13
14class <Name>Agent(BaseAgent):
15    """<Name> Agent — <brief description>"""
16
17    def __init__(self, skill_registry: SkillRegistry, **kwargs):
18        # Discover and register all skills from skills/ subdirectory
19        agent_dir = Path(__file__).parent
20        skills = SkillLoader.load_agent_skills(agent_dir, lazy=skill_registry._lazy)
21        for skill in skills:
22            skill_registry.register(skill)
23
24        super().__init__(skill_registry, **kwargs)
25
26        # If agent has tools, register them here:
27        # from .skills.<skill_name>.tools.<tool_module> import <tool>
28        # self.register_tools([<tool>])
29
30    @property
31    def agent_name(self) -> str:
32        return "<Name>Agent"
33
34    @property
35    def default_skills(self) -> list[str]:
36        return ["<skill_name>"]
37
38    @property
39    def base_system_prompt(self) -> str:
40        return """<system prompt for this agent>"""
41
42    def process(self, messages: list[BaseMessage], **kwargs) -> dict:
43        response = self.invoke(messages)
44        content = response.content
45        return {
46            "result": content,
47            "raw_response": response,
48        }

Step 4: Write package __init__.py

Create src/agents/<name>/__init__.py:

python
1"""
2<Name> Agent Package
3"""
4
5from .agent import <Name>Agent
6
7__all__ = ["<Name>Agent"]

Step 5: Register in src/agents/__init__.py

Add the import and export:

python
1from .<name> import <Name>Agent

And add "<Name>Agent" to the __all__ list.

Step 6: Add to workflow graph

Edit src/graph/workflow.py:

1. Import the new agent class in the imports section.

2. Instantiate it in create_workflow() alongside the other agents:

   python
   1<name> = <Name>Agent(skill_registry, **agent_kwargs)

3. Define a node function following the existing pattern:

   python
   1def <name>_node(state: AgentState) -> dict:
   2    input_data = {"messages": state["messages"]}
   3    result = <name>.process(state["messages"])
   4    output = {
   5        "current_agent": "<name>",
   6        # map result keys to AgentState fields as needed
   7    }
   8    _log_agent("<Name>Agent", input_data, output)
   9    return output

4. Register the node:

   python
   1workflow.add_node("<name>", <name>_node)

5. Add edges — connect the node to the graph with add_edge or add_conditional_edges depending on the routing logic.

6. If the new agent's output needs a new state field, add it to AgentState in src/graph/state.py and to create_initial_state().

Step 7: Update router

If the router should be able to route to this new agent:

1. Add the new route to RouterAgent.VALID_ROUTES in src/agents/router/agent.py.

2. Add the route description to RouterAgent.base_system_prompt.

3. Update src/agents/router/skills/routing/SKILL.md with a new section describing when to route to this agent.

4. Update route_decision() in src/graph/workflow.py to handle the new route value.

Step 8: Run verification

Run the verification skill to confirm nothing is broken:

bash
1uv run python -c "import src.main; import src.graph; import src.agents; import src.skills"
2uv run python -m src.main --test

Expected: "Workflow created successfully", correct skill count, "All tests passed".