Creating Greybeard Agents

This guide shows you how to build new agents on top of the Greybeard framework.

Quick Start

1. Create Your Agent File

# Create a new agent in greybeard/agents/your_agent_name/
mkdir -p greybeard/agents/your_agent_name
touch greybeard/agents/your_agent_name/__init__.py
touch greybeard/agents/your_agent_name/agent.py

2. Implement Your Agent

# greybeard/agents/your_agent_name/agent.py

from greybeard.common import BaseAgent

class YourAgent(BaseAgent):
    """Brief description of what your agent does."""

    def __init__(self):
        super().__init__(
            name="your-agent-name",
            description="What this agent helps with",
        )

    def run(self, user_input: str) -> dict:
        """Execute the agent.

        Args:
            user_input: Initial user question or input

        Returns:
            Dictionary with results
        """
        # Your implementation here
        return {
            "result": "something",
            "analysis": "details",
        }

3. Write Tests

# tests/test_your_agent.py

import pytest
from greybeard.agents.your_agent_name.agent import YourAgent

def test_agent_initialization():
    agent = YourAgent()
    assert agent.name == "your-agent-name"

def test_agent_run():
    agent = YourAgent()
    result = agent.run("test input")
    assert "result" in result

Available Capabilities

All agents inherit these capabilities from BaseAgent:

LLM Capability

Call the configured language model:

def run(self, user_input: str) -> dict:
    response = self.llm.call(
        system="You are an expert...",
        messages=[
            {"role": "user", "content": user_input}
        ],
        temperature=0.7,
    )
    return {"response": response}

Methods: - call(system, messages, temperature, model_override) - Synchronous call - stream_call(...) - Streaming call - get_config() - Get current configuration - reload_config() - Reload from disk

Research Capability

Gather context and information:

def run(self, user_input: str) -> dict:
    # Analyze directory structure
    structure = self.research.analyze_structure("/path/to/dir")

    # Get file context
    content = self.research.gather_file_context("/path/to/file.txt")

    # Get git repository info
    git_info = self.research.get_git_context(".")

    # Load JSON data
    data = self.research.load_json_data("/path/to/data.json")

    # Research a topic
    summary = self.research.research_topic("kubernetes")

    return {"structure": structure, "git": git_info}

Methods: - research_topic(topic, sources) - Research a topic - gather_file_context(filepath) - Read file content - analyze_structure(dirpath) - Analyze directory structure - get_git_context(repo_path) - Get git repository info - load_json_data(filepath) - Load and parse JSON

Interview Capability

Conduct multi-turn conversations:

def run(self, user_input: str) -> dict:
    # Start interview session
    self.interview.start_interview(
        opening_question="Tell me about your decision",
        topic="career decision"
    )

    # Ask question
    response = self.interview.ask_question("Why are you considering this?")

    # Get accumulated context
    context = self.interview.get_context()

    # Get conversation history
    history = self.interview.get_history()

    # Summarize
    summary = self.interview.summarize_interview()

    return {"summary": summary, "history": history}

Methods: - start_interview(opening_question, topic) - Begin interview - ask_question(question) - Ask user a question - ask_followup(response, system, llm_call) - Generate AI followup - get_history() - Get conversation history - get_context() - Get accumulated context - add_context(key, value) - Add context value - summarize_interview() - Get conversation summary - clear() - Clear history and context

Documentation Capability

Format and save outputs:

def run(self, user_input: str) -> dict:
    # Format output
    markdown = self.documentation.format(
        content="# Header\n\nContent",
        format_type="markdown",
        metadata={"version": "1.0"}
    )

    # Create template
    template = self.documentation.create_template(
        title="Decision Document",
        sections={
            "Context": "Explain context",
            "Decision": "What you decided",
        },
        metadata={"date": "2026-03-18"}
    )

    # Save files
    self.documentation.save_markdown(markdown, "/path/to/output.md")
    self.documentation.save_json({"data": "value"}, "/path/to/output.json")

    return {"output": markdown}

Methods: - format(content, format_type, metadata) - Format content (markdown/json/yaml) - create_template(title, sections, metadata) - Create template - save_markdown(content, filepath) - Save markdown file - save_json(data, filepath) - Save JSON file - save_yaml(data, filepath) - Save YAML file

Multi-Turn Conversation

For agents that need interactive conversations:

def run(self, user_input: str) -> dict:
    # Run multi-turn conversation
    result = self.multi_turn_conversation(
        initial_question=user_input,
        max_turns=10,
        expected_completion_fn=self._is_conversation_complete,
    )

    return {"result": result, "history": self.conversation_history}

def _is_conversation_complete(self, response: str) -> bool:
    """Check if conversation is complete."""
    # Return True when conversation should end
    return "final answer" in response.lower()

Parameters: - initial_question (str) - The opening question - max_turns (int) - Maximum conversation turns (default 10) - expected_completion_fn (callable) - Function to check if done

State Management

Agents maintain state across runs:

def run(self, user_input: str) -> dict:
    # Access conversation history
    history = self.conversation_history
    # [{"role": "user", "content": "..."}, ...]

    # Access accumulated context
    context = self.context
    # {"key": "value", ...}

    # Modify context
    self.context["analysis_result"] = "something"

    # Save conversation
    self.save_conversation("/path/to/conversation.json")

    return {"result": "done"}

Real-World Example: Architecture Decision Agent

from greybeard.common import BaseAgent

class ADRAgent(BaseAgent):
    """Help teams write Architecture Decision Records."""

    def __init__(self):
        super().__init__(
            name="architecture",
            description="Document architectural decisions properly",
        )

    def run(self, decision_question: str) -> dict:
        # Interview about decision
        self.interview.start_interview(
            opening_question=f"Help me document: {decision_question}",
            topic="architecture decision"
        )

        # Gather context
        alternatives = self.research.research_topic(decision_question)

        # Multi-turn conversation for ADR generation
        adr_draft = self.multi_turn_conversation(
            initial_question=decision_question,
            expected_completion_fn=self._is_adr_complete
        )

        # Format as markdown ADR
        adr_markdown = self.documentation.create_template(
            title=f"ADR: {decision_question}",
            sections={
                "Context": "Why are we making this decision now?",
                "Decision": "What are we going to do?",
                "Consequences": "What are the good and bad outcomes?",
                "Alternatives": "What else did we consider?",
            },
            metadata={"status": "Proposed", "date": str(datetime.now())}
        )

        return {
            "adr": adr_markdown,
            "alternatives": alternatives,
            "conversation": self.conversation_history,
        }

    def _is_adr_complete(self, response: str) -> bool:
        """Check if ADR draft is complete."""
        return all(
            section in response.lower()
            for section in ["context", "decision", "consequences"]
        )

Testing Your Agent

import pytest
from unittest.mock import Mock, patch
from your_agent import YourAgent

class TestYourAgent:

    def test_initialization(self):
        agent = YourAgent()
        assert agent.name == "your-agent-name"

    def test_run_basic(self):
        agent = YourAgent()
        result = agent.run("test input")
        assert isinstance(result, dict)

    def test_with_mocked_llm(self):
        agent = YourAgent()
        agent.llm.call = Mock(return_value="Mocked response")

        result = agent.run("test")

        assert "Mocked response" in result.get("result", "")

    def test_conversation_flow(self):
        agent = YourAgent()

        with patch('rich.prompt.Prompt.ask') as mock_ask:
            mock_ask.side_effect = ["Answer 1", "Answer 2"]

            agent.interview.start_interview("Opening?", "test")
            agent.interview.ask_question("Q1?")
            agent.interview.ask_question("Q2?")

        assert len(agent.interview.get_history()) == 2

Publishing Your Agent

To share your agent:

1. Create a PR with your agent implementation
2. Include tests (aim for 80%+ coverage)
3. Add documentation explaining what it does
4. Update CONTRIBUTING.md if you're adding a new agent

Example PR title:

feat: add [agent-name] agent

Adds [AgentName] agent for [purpose].

Includes:
- Agent implementation
- Comprehensive tests
- Documentation with examples
- Integration examples

Best Practices

1. Keep agents focused - Each agent solves one problem well
2. Use all capabilities - Leverage research, interview, docs
3. Test thoroughly - Aim for 80%+ coverage
4. Document well - Include docstrings and examples
5. Handle errors gracefully - Use try/except, provide feedback
6. Accumulate context - Use self.context to build knowledge
7. Track history - self.conversation_history is your audit trail

Common Patterns

Pattern 1: Interview → Analysis → Output

def run(self, user_input):
    # Interview user
    self.interview.start_interview(user_input, "analysis")
    context = self.interview.ask_question("Tell me more")

    # Analyze with LLM
    analysis = self.llm.call(
        system="Analyze this:",
        messages=[{"role": "user", "content": context}]
    )

    # Format and return
    output = self.documentation.format(analysis, "markdown")
    return {"analysis": output}

Pattern 2: Research → Synthesis → Documentation

def run(self, user_input):
    # Research the topic
    git_info = self.research.get_git_context(".")
    structure = self.research.analyze_structure(".")

    # Synthesize with LLM
    synthesis = self.llm.call(
        system="Summarize this infrastructure",
        messages=[{
            "role": "user",
            "content": f"Git: {git_info}\nStructure: {structure}"
        }]
    )

    # Document
    doc = self.documentation.create_template(
        title="Infrastructure Summary",
        sections={"Analysis": synthesis}
    )

    return {"documentation": doc}

Pattern 3: Multi-Turn Conversation

def run(self, user_input):
    # Interactive conversation
    result = self.multi_turn_conversation(
        initial_question=user_input,
        expected_completion_fn=self._done,
    )

    # Save results
    self.documentation.save_markdown(result, "output.md")

    return {
        "result": result,
        "turns": len(self.conversation_history)
    }

def _done(self, response):
    return "done" in response.lower()

Questions?

Refer to: - greybeard/common/agent.py - BaseAgent implementation - examples/ - Real agent examples - tests/ - Test patterns and fixtures