Skip to main content

2. Add Subagents

A subagent is an agent that a model step calls as a tool. Each subagent has its own instructions, model and tools, and it returns its answer to the step that called it. In this page, the review step calls two subagents: a security reviewer and a test reviewer. Each one looks at one thing only. The review step merges their findings with its own.

A subagent is different from a step. You decide the order of steps in agent.yaml. The model decides when to call a subagent, what to give it, and what to do with the answer.

Before you start​

Do page 1 first. This page changes the review step inside the size step.

Step 1: Add two inline subagents​

In agent.yaml, add this subagents field to the review step, below integration_tools. Keep the indent of the other fields of the step:

YAML
        subagents:
security_reviewer:
description: >-
Reviews the diff for security problems only. Give it the diff
file and the folder of the clone.
instructions: |
You check one pull request for security problems only:
secrets in the code, unsafe input, missing permission checks,
and errors that hide failures. The prompt gives the diff file
and the folder of a clone of the repository. Read them in
your shell.
Return each finding on one line: the severity, the file and
line, the problem, and the fix. If you find nothing, say so.
model: claude-haiku-5-5
system_tools: operation_type == "read"
test_reviewer:
description: >-
Says what the tests do not cover in the diff. Give it the diff
file and the folder of the clone.
instructions: |
You check one pull request for missing tests only. The prompt
gives the diff file and the folder of a clone of the
repository. Read them in
your shell, and find the tests for the changed code.
Say which changed behavior has no test, and the test to add.
Return one line per missing test.
model: claude-haiku-5-5
system_tools: operation_type == "read"
PartWhat it does
security_reviewer, test_reviewerThe keys. Each key gives the review step a tool named invoke_<key>, for example invoke_security_reviewer. Keys are snake_case.
descriptionWhat the review step reads to decide when to call the subagent and what to give it.
instructionsThe subagent's own system prompt. An inline subagent must have description and instructions.
model, system_toolsThe subagent's own model and tool filter.

These subagents are inline: they live in the parent's agent.yaml. A subagent can also be another agent of the project, written as agent: agents:<id>. See Referencing existing agents.

Step 2: Tell the review step to call them​

Replace the numbered list in instructions.md with this list:

MARKDOWN
1. An earlier step downloaded the diff of the pull request to a file. The prompt gives its path. Read it.
2. Clone the repository with the `git_clone` tool. Give it the repository's https URL and the ref `pull/<number>/head`. Read the changed files in full in the clone, not only the diff.
3. Call `invoke_security_reviewer` and `invoke_test_reviewer` at the same time. Give each one the diff file and the folder of the clone.
4. Merge their findings with your own. Remove duplicates.
5. Write a verdict: merge, merge with changes, or do not merge.
6. Name the riskiest change, with its file and line.
7. Ask the author one question.

Keep the rest of the file. The subagents use the same sandbox as the run, so they can read the diff file and the clone. They do not see the conversation of the review step. They see only the prompt that the review step gives them.

Step 3: Commit and run​

  1. Commit and run

    Commit the 2 files. On the agent's Overview tab, paste https://github.com/autohealai/astronomy-shop-template/pull/1 and click Start run.

  2. Find the subagent calls

    Open the Transcript tab and open the Review the diff row. Check that the conversation has a card for each subagent, after the review step read the diff. The review step sends both calls at the same time.

  3. Read a subagent's work

    Open the card of the test reviewer to read its work and its answer. Check that the test reviewer says that the recommendation service has no test for the new timeout or for the error path.

  4. Read the merged review

    Open the Summary tab. Check that the review has the findings of all three reviewers. The review must name the timeout in the wrong unit and the setting name that is different in the README and in the code. It must also name the except Exception that hides catalog errors, and the missing test.

What to know​

  • The model decides whether to call a subagent. Name the invoke_<key> tools in the instructions, and say when to call them, as in step 2.
  • A subagent can use only the tools that both its own filter and its caller's filters keep.
  • An inline subagent cannot have its own subagents. To go one level deeper, make the subagent a separate agent and refer to it with agent: agents:<id>.
  • One run can have at most 4 subagent calls in progress at the same time. A fifth call fails with SubagentConcurrencyError, and the model can send it again later. See Concurrent subagent calls.
  • Each subagent call costs tokens. A small, cheap model, such as claude-haiku-5-5, is often enough for a subagent with a narrow task.
  • The cost and the tokens of a run include its subagents. In the transcript, the answer of each invoke_<key> call shows the subagent's cost and model requests.

From the CLI​

BASH
autoheal agents push agents/pr-review-steps -m "Add security and test subagents"
autoheal run pr-review-steps "https://github.com/autohealai/astronomy-shop-template/pull/1" --commit <sha> --follow

--follow prints the transcript. Check that it has the lines → invoke_security_reviewer(...) and → invoke_test_reviewer(...), and a ← line with the answer of each one. The push also prints the tools that each subagent gets.

See Subagents and Inline subagents in the reference.