Subagents

Subagents are specialized agents launched by the main Agent through the Task tool. They let the main agent delegate focused work (like exploration or implementation) while keeping tool access and behavior scoped.

Custom subagents

Custom subagents are user-defined agent profiles. You can create them either in the UI or by editing your config file.

Each custom subagent has:

A title (this is the value you pass in subagent_type)
An objective/behavior description
An optional runtime override
A tool allowlist that controls what it can do

Create in the UI

Open settings and go to Subagents.
Click Add (or Generate if you want ProxyAI to draft it from a prompt).
Set the title, objective, runtime, and allowed tools.
Save.

Create via settings.json

You can also add subagents directly in your project's .proxyai/settings.json.

Subagent definition fields

Field	Type	Required	Description
`id`	number	Yes	Unique numeric ID for this subagent.
`title`	string	Yes	Display name and the value you pass as `subagent_type`.
`objective`	string	Yes	Instructions that shape how the subagent behaves.
`tools`	string[]	Yes	Allowed tools, stored as lowercase tool IDs (for example `read`, `intellijsearch`, `edit`).
`provider`	string	No	Native provider override. Must be paired with `model`.
`model`	string	No	Native model override. Must be paired with `provider`.
`external_agent_id`	string	No	External ACP runtime preset ID (for example `codex`).

If you omit provider, model, and external_agent_id, the subagent inherits the parent Agent runtime.

Example:

{
  "subagents": [
    {
      "id": 200,
      "title": "Dependency Researcher",
      "objective": "Help choose the best dependency for the user's topic (e.g., auth, logging, HTTP, testing). Compare 2-4 realistic options, call out licensing, maintenance signals, and ecosystem fit. Prefer reading existing repo usage first, then use Context7 for API details, and WebSearch only for release notes/security/official docs. Provide a short recommendation with sources.",
      "provider": "OPENAI",
      "model": "gpt-5-mini",
      "tools": [
        "read",
        "intellijsearch",
        "resolvelibraryid",
        "getlibrarydocs",
        "websearch",
        "todowrite",
        "exit"
      ]
    }
  ]
}

Generate subagents

If you don't want to hand-write subagent definitions, you can generate one from natural language in the UI.

Steps

Open settings and go to Subagents.
Click Generate.
Describe what you want (for example: "Review Kotlin code for style and complexity").
Review the generated title and objective.
Adjust the tool allowlist if needed, then save.

Notes

Generation creates the title and objective text. Tool access is suggested based on your prompt, but it's still your call.
If your prompt includes words like "edit", "implement", or "modify", ProxyAI will usually suggest write-capable tools.

Task input reference

When the agent spawns a subagent, it calls the Task tool with the inputs below.

Field	Type	Required	Description
`description`	string	Yes	Short label for the run.
`prompt`	string	Yes	Full instruction for the subagent.
`subagent_type`	string	Yes	Which subagent to run (built-in type or a custom title).
`model`	string	No	Optional native-model override for that subagent run. ProxyAI rejects this when the resolved runtime is external.
`project_path`	string	No	Optional working directory override.

How subagents are surfaced

Subagent tool calls are bridged back to the parent agent run so the UI can display them and approval prompts still work as expected.

The task row also shows the resolved runtime as soon as the subagent starts, for example:

OpenAI · GPT-5
Anthropic · Claude 4.5 Sonnet
Codex