Creating and Managing Agents

Create your own agent for Qodo Gen CLI to use, then run Qodo Gen CLI with a customizable command.

1. Create an agent file

Before starting to use Qodo Gen CLI, make sure you've logged in to Qodo.

Create a file <your-command-name-here>.toml and save it under a folder called agents.

2. Customize your agent

Follow the skeleton and customize your agent to your needs. You can set instructions, import existing agents configurations for your agent to use, and give it tools to utilize.

Name your agent file after the command you want to use to run it. This name should also appear in the file itself, under the commands section.

The fields of the agent file are:

Field name	Type	Description
description	string	Description of what your agent does
instructions	string	Prompt for the AI models explailing the required behavior
arguments	list of objects	List of possible arguments that can be given to the agent. The arguments will be translated and forwarded to MCP servers.
mcpServers	string	List of MCP servers used by the agent
available_tools	list	List of MCP server names
execution_strategy	"act" or "plan"	Plan lets the agent think through a multi-step strategy, act executes actions immediately
output_schema	string	Valid json of the wanted agent output
exit_expression	string	For CI runs, a condition used to determine if the agent run succeeded or failed

Example agent TOML file

# 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 you'd like your agent to be able to use
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"

3. Set output type

You can give your agent a json schema to follow as its output.

If there’s no output schema given, your agent will output a textual summary as a reply for a query.

4. Create an agent.toml file

Add your agent to a file called agent.toml. This file will hold all agent files that Qodo Gen CLI will know and be able to call. Example agent.toml file:

# Version of the agent configuration standard
version = "1.0"

model = "claude-4-opus"

imports = [
    "agents/explain.toml",
    "agents/review.toml",
    "agents/test_codebase.toml",
    ... # more agents
]

5. Use your agent

You can now run your agent by calling:

qodo <command_name>

---

mcp.json file

You can define MCP servers to be used by agents in a file called mcp.json. This will make the MCP servers available to all agents you're configuring.

Once configured in the mcp.json file, these tools can be mentioned under the available_tools section in your agent file to be used by your agent.

If you want a specific MCP server for your agent that doesn't need to be reused for other agents, you can define it in the specific agent configuration TOML file.

---

Agent Modes

Agent as server: the --mcp flag

You can also run an agent as a tool server:

qodo <command_name> --mcp

This launches the agent as a service listening on port 3000.

The service can be integrated with other AI tools or exposed via URL.

You can exit at any time by pressing Escape.

---

Qodo and Community Agent Examples

Check out Qodo's agent repository in GitHub to see examples of working agents.