🚧 PROJECT STATUS: This repository is under active development. We welcome contributions to help build some cool agents!
A curated collection of reference agent implementations for the Qodo CLI framework, showcasing best practices and common patterns for building AI-powered development workflows.
Qodo Agents are configurable AI workflows that combine:
- Instructions: Natural language prompts that define the agent's behavior
- Tools: MCP servers and external integrations the agent can use
- Arguments: Configurable parameters for customization
- Execution Strategy: How the agent approaches tasks (plan vs act)
- Output Schema: Structured output format for integration
- Exit Expressions: Success/failure conditions for CI/CD
These agents demonstrate core patterns and best practices for the Qodo framework.
- Code Review - Comprehensive code review with Qodo Merge integration
- Diff Test Generation - Automated test suite creation and validation of code changes
- GitHub Issue Handler - Automatically processes GitHub issues by analyzing content, answering questions, implementing fixes, and creating pull requests
Community-contributed agents demonstrating various use cases and integrations.
Note: Community agents are maintained by their respective authors and should be used at your own discretion.
- Planning Agents - Multi-step strategic approaches
- Action Agents - Direct execution patterns
- MCP-Based - Leveraging Model Context Protocol servers
- API-Based - Direct API integrations
- Tool-Based - Command-line tool integrations
- Structured Data - JSON/YAML output for automation
- Reports - Human-readable analysis
- Actions - Direct system modifications
- Qodo CLI installed
- Node.js 18+ and npm
- Git for version control
-
Clone this repository:
git clone https://github.com/qodo-ai/agent-reference-implementations.git cd agent-reference-implementations -
Choose an agent:
# Copy a reference agent to your project cp -r src/code-review/ /path/to/your/project/agents/ -
Configure the agent:
# Edit the agent configuration vim /path/to/your/project/agents/code-review/agent.toml -
Run the agent:
cd /path/to/your/project qodo code-review --agent-file=agents/code-review/agent.toml
Each reference agent includes:
- Configuration file (
agent.tomloragent.yaml) - README with usage instructions and examples
- Test cases demonstrating expected behavior
- Integration examples for common scenarios
# agent.toml
version = "1.0"
[commands.my_agent]
description = "Detailed description for users"
instructions = """
Your agent's behavior instructions here.
Be specific about the task and expected outcomes.
"""
# Optional: Define arguments
arguments = [
{ name = "input_file", type = "string", required = true, description = "Input file path" },
{ name = "threshold", type = "number", required = false, default = 0.8, description = "Quality threshold" }
]
# Optional: MCP servers your agent uses
mcpServers = """
{
"shell": {
"command": "uvx",
"args": [
"mcp-shell-server"
],
"env": {
"ALLOW_COMMANDS": "..."
}
},
"github": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN",
"ghcr.io/github/github-mcp-server"
]
}
}
"""
# Optional: Define available tools
available_tools = ["filesystem", "git", "shell", "github"]
# Optional: Define execution strategy: "plan" for multi-step, "act" for direct execution
execution_strategy = "act"
# Optional: Define expected output structure
output_schema = """
{
"properties": {
"success": {"type": "boolean"},
"results": {"type": "array", "items": {"type": "string"}},
"score": {"type": "number"}
}
}
"""
# Optional: Success condition for CI/CD
exit_expression = "success"- Clear Instructions: Write specific, actionable instructions
- Proper Tool Selection: Choose appropriate MCP servers and tools
- Error Handling: Include error scenarios in instructions
- Testing: Provide test cases and expected outputs
- Documentation: Include comprehensive README and examples
# Test with sample data
qodo my_agent --input_file=test/sample.txt --threshold=0.9
# Validate output schema
qodo my_agent --input_file=test/sample.txt | jq '.success'
# CI/CD integration test
qodo my_agent --ci --input_file=test/sample.txt- Basic Agent Tutorial ✅ - Creating and managing agents
- MCP Server Integration ✅ - Model Context Protocol documentation
- CI/CD Integration ✅ - CI and automation with Qodo CLI
- Output Schema Design 🚧 Not yet available
- Agent Design Patterns 🚧 Not yet available
- Performance Optimization 🚧 Not yet available
- Security Considerations 🚧 Not yet available
We welcome contributions! Please see our Contributing Guide for details.
- Reference Agents: Submit well-documented, tested agents
- Community Agents: Share your specialized use cases
- Documentation: Improve guides and examples
- Bug Reports: Report issues with existing agents
- Follow the Agent Development Guidelines
- Include comprehensive tests and documentation
- Ensure compatibility with latest Qodo CLI version
- Add your agent to the appropriate category in this README
This project is licensed under the MIT License - see the LICENSE file for details.
- Qodo CLI - The main Qodo CLI framework
- Model Context Protocol - Protocol for AI tool integration
- MCP Servers - Reference MCP server implementations
If you find these agent implementations useful, please consider:
- Starring this repository
- Contributing your own agents
- Sharing feedback and suggestions
- Helping improve documentation
Built with ❤️ by the Qodo community