🛠️ Creating Custom Agents

# 🛠️ Creating Custom Agents

This guide shows you how to create specialist agents for any domain. No subclassing, no boilerplate — just `Agent(name=..., system_prompt=..., tools=..., tool_map=...)`.

---

## The Pattern

```python
from lib.agents import Agent, ManagerAgent
from lib.tools  import ALL_TOOLS, TOOL_MAP

my_agent = Agent(
    name          = "MyAgent",
    system_prompt = "You are a specialist in X...",
    tools         = ALL_TOOLS,    # give it the execute_command tool
    tool_map      = TOOL_MAP,
)
```

That's it. The agent is ready to run.

---

## Recipe 1 — Tool-Using Specialist Agent

An agent that uses the shell to interact with external systems (browser, Jira, GitHub, APIs):

```python
from lib.agents import Agent
from lib.tools  import ALL_TOOLS, TOOL_MAP
from lib.config import SKILLS_DIR, SCREENSHOTS_DIR

browser_agent = Agent(
    name = "Browser",
    system_prompt = f"""You are a browser automation specialist.

## ⚠️ MANDATORY FIRST STEP
Before doing ANYTHING, read your skill documentation:
    cat {SKILLS_DIR}/agent-browser/SKILL.md

## Workflow
1. Read skill file (always first)
2. Open the URL and wait for full load
3. Take a snapshot to see element refs
4. Interact using refs — re-snapshot after navigation
5. Save screenshots to {SCREENSHOTS_DIR}/<name>.png
6. Close browser when done
7. Return a clear summary of what you found""",
    tools    = ALL_TOOLS,   # has execute_command
    tool_map = TOOL_MAP,
)

result = browser_agent.run("Go to https://news.google.com and extract the top 5 headlines")
```

---

## Recipe 2 — Pure Reasoning Agent (no tools)

An agent that takes input text and produces structured output using only LLM reasoning — no tool calls:

```python
writer_agent = Agent(
    name = "Writer",
    system_prompt = """You are a professional technical writer.
You receive raw data and produce clear, structured markdown reports.

Always include:
- Executive summary
- Detailed findings section
- Recommendations
- Conclusion""",
    tools    = [],    # no tools — pure LLM
    tool_map = {},
)

raw_data = "Page title: Dashboard. Sections: Revenue ($12k), Users (340), Orders (18)..."
result = writer_agent.run(f"Write a report based on this data:\n{raw_data}")
```

---

## Recipe 3 — Multi-Step Pipeline with ManagerAgent

Wire multiple specialist agents into a manager that routes tasks automatically:

```python
from lib.agents import Agent, ManagerAgent
from lib.tools  import ALL_TOOLS, TOOL_MAP

# Step 1 — declare agents
scraper = Agent(
    name          = "Scraper",
    system_prompt = "You extract raw data from websites using the browser skill...",
    tools         = ALL_TOOLS,
    tool_map      = TOOL_MAP,
)

analyser = Agent(
    name          = "Analyser",
    system_prompt = "You analyse raw data and identify key insights and patterns...",
    tools         = [],   # pure reasoning
    tool_map      = {},
)

reporter = Agent(
    name          = "Reporter",
    system_prompt = "You write polished executive reports from analysis outputs...",
    tools         = ALL_TOOLS,   # needs execute_command to save reports
    tool_map      = TOOL_MAP,
)

# Step 2 — plug into manager
manager = ManagerAgent(
    agents = {
        "scraper":   scraper,
        "analyser":  analyser,
        "reporter":  reporter,
    }
)

# Step 3 — run
result = manager.run(
    "Scrape product prices from example.com/products, "
    "analyse pricing trends, and write an executive report"
)
```

### What the manager's tool schema looks like (auto-generated):

```json
{
  "name": "call_agent",
  "parameters": {
    "agent_name": {
      "enum": ["scraper", "analyser", "reporter"]  ← auto-built from agents dict
    },
    "task": "string"
  }
}
```

---

## Recipe 4 — Custom Tool (API Integration)

Add a custom tool to an agent — for example, a Slack notification tool:

```python
import requests

# 1. Define the executor function
def send_slack_message(message: str, channel: str = "#general") -> str:
    """Send a message to Slack via webhook."""
    webhook_url = "https://hooks.slack.com/services/..."
    resp = requests.post(webhook_url, json={"text": message, "channel": channel})
    return f"Sent to {channel}: HTTP {resp.status_code}"

# 2. Define the OpenAI tool schema
SLACK_TOOL = {
    "type": "function",
    "function": {
        "name": "send_slack_message",
        "description": "Send a notification message to a Slack channel",
        "parameters": {
            "type": "object",
            "properties": {
                "message": {"type": "string", "description": "The message to send"},
                "channel": {"type": "string", "description": "Slack channel name"},
            },
            "required": ["message"],
        },
    },
}

# 3. Combine with existing tools
from lib.tools import ALL_TOOLS, TOOL_MAP

notifier_agent = Agent(
    name          = "Notifier",
    system_prompt = "You are a monitoring agent. When you detect issues, notify the team via Slack.",
    tools         = ALL_TOOLS + [SLACK_TOOL],
    tool_map      = {**TOOL_MAP, "send_slack_message": send_slack_message},
)
```

---

## Customising Memory Behaviour

```python
# Agent that handles very large pages — prune aggressively
browser = Agent(
    name             = "Browser",
    system_prompt    = "...",
    tools            = ALL_TOOLS,
    tool_map         = TOOL_MAP,
    max_tool_history = 2,     # keep only last 2 full results (default: 3)
    trim_to          = 200,   # trim older ones to 200 chars (default: 400)
)

# Agent for small focused tasks — keep more context
jira = Agent(
    name             = "Jira",
    system_prompt    = "...",
    tools            = ALL_TOOLS,
    tool_map         = TOOL_MAP,
    max_tool_history = 5,     # bigger window
    trim_to          = 800,   # more chars from old results
)

# Agent that should never prune (small tasks, testing)
simple = Agent(
    name             = "Simple",
    system_prompt    = "...",
    tools            = ALL_TOOLS,
    tool_map         = TOOL_MAP,
    max_tool_history = 0,     # disabled — original behaviour
)
```

---

## System Prompt Writing Guide

The system prompt is the most important thing to get right. Follow this structure:

```
## Role Statement (1 sentence)
You are <Name>, a specialist in <domain>.

## ⚠️ MANDATORY FIRST STEP (for tool-using agents)
Before doing anything, read:
    cat <skill_file_path>

## Your Job / Workflow (numbered steps)
1. ...
2. ...
3. ...

## Output Rules
- Where to save files
- What format to return
- What to include in the summary

## Rules / Constraints
- Any guardrails or restrictions
```

### Tips for effective system prompts

| ✅ Do | ❌ Avoid |
|---|---|
| Give numbered workflow steps | Vague instructions like "do your best" |
| Specify exact file paths for output | Relative paths without anchoring |
| Tell the agent what to return | Leaving the output format implicit |
| Mandate reading the skill file first | Assuming the agent knows the CLI |
| Include all credentials in the task | Storing secrets in system prompts |

---

## Complete Example: 4-Agent QA Pipeline

```mermaid
flowchart LR
    Main["MainAgent\n(Manager)"]
    Jira["JiraAgent\nFetches ticket\n→ public/tickets/"]
    Browser["BrowserAgent\nPerforms test\n→ public/findings/\n→ public/screenshots/"]
    Doc["DocumentatorAgent\nWrites report\n→ public/docs/"]

    Main -->|"Step 1"| Jira
    Jira -->|"result"| Main
    Main -->|"Step 2"| Browser
    Browser -->|"result"| Main
    Main -->|"Step 3"| Doc
    Doc -->|"result"| Main
```

```python
from lib.agents import Agent, ManagerAgent
from lib.tools  import ALL_TOOLS, TOOL_MAP
from lib.config import SKILLS_DIR, SCREENSHOTS_DIR, DOCS_DIR

JIRA_SKILL    = f"{SKILLS_DIR}/jira-cli/SKILL.md"
BROWSER_SKILL = f"{SKILLS_DIR}/agent-browser/SKILL.md"
TICKETS_DIR   = "public/tickets"
FINDINGS_DIR  = "public/findings"
ISSUE_ID      = "PROJ-123"

agent_jira = Agent(
    name          = "Jira",
    system_prompt = f"Read {JIRA_SKILL} first. Fetch {ISSUE_ID} and save to {TICKETS_DIR}/{ISSUE_ID}.md",
    tools         = ALL_TOOLS,
    tool_map      = TOOL_MAP,
)

agent_browser = Agent(
    name          = "Browser",
    system_prompt = f"Read {BROWSER_SKILL} first. Read {TICKETS_DIR}/{ISSUE_ID}.md. Perform the test. Save findings to {FINDINGS_DIR}/{ISSUE_ID}_findings.md",
    tools         = ALL_TOOLS,
    tool_map      = TOOL_MAP,
)

agent_doc = Agent(
    name          = "Documentator",
    system_prompt = f"Read {FINDINGS_DIR}/{ISSUE_ID}_findings.md and {TICKETS_DIR}/{ISSUE_ID}.md. Write report to {DOCS_DIR}/{ISSUE_ID}_report.md",
    tools         = ALL_TOOLS,
    tool_map      = TOOL_MAP,
)

manager = ManagerAgent(
    agents = {"jira": agent_jira, "browser": agent_browser, "documentator": agent_doc},
    system_prompt = f"""Run the QA pipeline for {ISSUE_ID} in order:
1. Call jira to fetch the ticket
2. Call browser to perform the test  
3. Call documentator to write the report"""
)

result = manager.run(f"Run full QA pipeline for {ISSUE_ID}")
```