Custom Agent Configurations

Updated on Oct 1, 2026

A custom agent is a named persona or instruction set that you define inside your AI coding agent, such as python-expert or security-reviewer. Forge can pass a custom-agent name for every workflow, for a target, or for one operation. Use custom agents when a workflow needs expertise that Forge's built-in roles do not cover.

Three separate options control a run:

Option	Selects
`-a, --agent <NAME>`	The AI coding agent CLI: `claude_code`, `github_copilot`, or `opencode`.
`--custom-agent <NAME>`	A custom agent defined inside that CLI.
`-m, --model <MODEL>`	The model. See AI Model Selection.

Prerequisites

A supported agent is installed and authenticated. See AI Coding Agent Setup.
The custom agent exists in that agent's own configuration. Forge does not create custom agents or check that the name exists. See your agent's documentation for how to define one.

How Forge selects a custom agent

For each workflow command, Forge uses the first value it finds:

The --custom-agent command-line option.
The custom_agent_operations entry for the operation, for example "issue.draft".
The custom_agents entry for the target, for example issue.
The agent-level custom_agent value.
No custom agent.

When a custom agent is selected, Forge leaves its built-in role prompt out of the composed prompt, and the custom agent supplies the persona. Without a custom agent, Forge includes the role prompt for the workflow.

Configure custom agents

Add the settings to the agent's table in .forge/config/agents.toml.

Agent default

toml

[agent.github_copilot]
custom_agent = "general-assistant"

By target

toml

[agent.github_copilot.custom_agents]
issue = "issue-specialist"
pr = "pr-reviewer"
code = "code-expert"
docs = "doc-writer"

With this configuration, frg issue draft uses issue-specialist and frg docs create uses doc-writer.

By operation

toml

[agent.github_copilot.custom_agent_operations]
"issue.plan" = "planning-expert"
"pr.review" = "senior-reviewer"
"code.review" = "quality-auditor"

Operation keys must use the target.operation form.

For one command

bash

frg pr review --custom-agent security-reviewer
frg code create --custom-agent python-expert --model claude-opus-5

The command-line value overrides everything in agents.toml for that run.

Example: combined precedence

toml

[agent.github_copilot]
custom_agent = "general-assistant"

[agent.github_copilot.custom_agents]
issue = "issue-specialist"

[agent.github_copilot.custom_agent_operations]
"issue.draft" = "draft-expert"

frg issue draft uses draft-expert (operation).
frg issue triage uses issue-specialist (target).
frg pr review uses general-assistant (agent default).
frg issue draft --custom-agent my-agent uses my-agent (command line).

Custom agents and roles

--role selects one of Forge's built-in roles: product_manager, software_engineer, software_architect, technical_writer, security_analyst, or sre.

--role and --custom-agent are mutually exclusive on the command line, so pass only one of them. If a custom agent comes from agents.toml, Forge skips the role prompt. To use a built-in role for a command that has a configured custom agent, remove the mapping or define the persona in the custom agent.

Settings reference

Setting	Location	Type	Purpose
`custom_agent`	`[agent.<agent_id>]`	String	Default custom agent for all targets and operations.
`custom_agents`	`[agent.<agent_id>.custom_agents]`	Table of strings	Maps a target name to a custom agent.
`custom_agent_operations`	`[agent.<agent_id>.custom_agent_operations]`	Table of strings	Maps a `target.operation` key to a custom agent.

All settings are optional and have no default. For command, model, and prompt_format, see Agent settings reference.

Troubleshooting

Warning: Empty custom agent string in agent '' at ''. Empty custom agent names are not allowed.

Cause: A custom-agent value is "".

Solution:

Open the entry named in <location>, for example custom_agents.issue.
Set a name or remove the entry.

Warning: Invalid custom_agent_operations key '' for agent ''. Expected format: 'target.operation' (e.g., 'issue.draft').

Cause: An operation key does not use the target.operation form.

Solution:

Rename the key, for example from issuedraft to "issue.draft". Quote keys that contain a dot.

The custom agent is not found or has no effect

Cause: The name does not exist in the agent CLI, a higher-precedence value applies, or the settings are under a different agent's table.

Solution:

Check that the custom agent exists in the agent CLI, with the exact spelling and letter case.
Check for --custom-agent on the command line.
Confirm that the settings are in [agent.<id>] for the agent that runs (agent.default or --agent).
Confirm that target mappings are in custom_agents and operation mappings are in custom_agent_operations.
Run frg config validate --file .forge/config/agents.toml and fix any warnings.

Verify: Run the command with --print-prompt. When a custom agent is active, the compiled prompt contains no built-in role prompt.

A built-in role does not apply

Cause: A custom agent is selected, so Forge leaves out the role prompt.

Solution:

Remove --custom-agent, or remove the matching entry from agents.toml.
Run the command with --role <ROLE>.