Subagent Briefs

By the Syncfusion DevTutorials team · Last updated October 21, 2026

Write a brief a subagent can follow and an orchestrator can merge: goal, inputs, allowed tools, output shape and done-when.

A Brief That Says Please

Some agents hand work to other agents.

Two words to know:

• Orchestrator = the main agent. It splits a big task into small ones.
• Subagent = a helper agent. It does one small task and sends back the result.

The orchestrator gives each subagent a short instruction.

• Brief = the instruction an orchestrator gives a subagent.

In this example, the brief is very friendly:

Please fix the dates in the export. Thanks!

The subagent tries hard. But it has to guess:

• It edits two files.
• It changes a helper nobody asked about.
• It sends back a long sentence about what it did.

None of this helps the orchestrator.

Simple lesson: a friendly brief is not a clear brief. The subagent only knows what the brief says.

A Real-World Example

An editor tells a reporter, "Write something about the match."

The reporter writes about the weather, the food and the parking.

The story is long, but the editor cannot use it.

An orchestrator and a subagent work the same way. A vague brief gets a useless answer.

Click the button and open the Agent tab.

• Agent tab: five GUESS lines. Each one is a part the brief left out.
• Preview & Checks: the orchestrator says REJECTED.

The subagent worked hard. The problem is the shape of the brief.

Simple lesson: the orchestrator is a program. It can only use an answer in the shape it expects.

TL;DR

1. Brief = the instruction an orchestrator gives a subagent.
2. A brief is a tiny spec for one task.

3. A good brief has five parts:

   • Goal = the one task to do
   • Inputs = what to read
   • Tools = what it may use
   • Output = the exact shape of the answer
   • Done when = the check that says the task is finished
4. Give only the tools the task needs.
5. Ask for the answer as data with exact fields, like JSON.
6. A sentence back is rejected. Data with every field is merged.

What You Will Learn

In this lesson, you will learn:

1. What an orchestrator and a subagent are.
2. The five parts of a good brief.
3. Why a subagent should get only a few tools.
4. Why the answer must have a fixed shape.
5. How "Done when" stops work at the right time.

The Five Parts of a Brief

Watch a brief grow, one part at a time:

Each new part turns one guess into a clear answer.

With all five parts, the subagent has nothing left to guess.

Goal

Goal = the one task the subagent must do.

Example:

Goal: Format every date in the export as YYYY-MM-DD.

A clear goal keeps the subagent on one task.

A vague goal invites extra changes nobody asked for.

Inputs

Inputs = the exact things the subagent should read.

These can be:

• files
• requirements
• acceptance criteria
• design notes

Example:

Inputs: src/features/export/exportOrders.ts, AC-2 in spec.md

Without inputs, the subagent searches everywhere. It may change the wrong file.

Tools

Tools = what the subagent is allowed to use.

A small fix usually needs only three:

• read files
• edit files
• run tests

Also say what is not allowed:

Tools: read, edit, test. No push, no install.

A subagent with too many tools can do things nobody wanted.

Output

Output = the exact shape of the answer.

Example:

Output: JSON {"file": string, "changed": number, "testsPassed": boolean}

The orchestrator does not read stories. It reads fields.

Every field it needs must be there.

Done When

Done when = the check that says the task is finished.

Example:

Done when: AC-2 (the date check) passes.

Without it, the subagent may:

• stop too early
• stop too late
• skip the tests

Simple lesson: five parts, five fewer guesses.

Structured Output

Why a Sentence Is Rejected

The orchestrator is a program.

A program cannot reliably read a sentence like this:

I updated the dates and everything should be fine now.

But it can read this:

{
  "file": "exportOrders.ts",
  "changed": 3,
  "testsPassed": true
}

So the brief must say the exact shape of the answer.

Watch the orchestrator check three answers:

• A sentence is rejected.
• Data with a missing field is rejected.
• Data with every field is merged.

Limit the Tools

Only What the Job Needs

A date fix needs to read, edit and test.

It does not need to:

• push code
• install packages
• deploy the app

Least privilege = give only the tools a task needs, nothing more.

Watch three different Tools lines:

Fewer tools means less can go wrong.

Simple lesson: if the task does not need a tool, do not give it.

Lab Exercise: Write a Brief the Orchestrator Can Merge

The orchestrator sends you a note. It tells you:

• the fields it needs in the answer
• the tools a subagent may use
• the file to change
• the check that means done

Use the note to write all five parts of the brief.

Press Check my spec.

If every part is clear, the orchestrator says MERGED.

Done When

Stop at the Right Time

A good "Done when" stops two problems:

• stopping before the tests run
• working forever

It should name a check that clearly passes or fails.

Example:

Done when: AC-2 passes.

Simple lesson: a subagent needs a finish line it can test.

What Changes per Tool

The file format is different in each tool.

The five parts of a good brief stay the same.

Common Mistakes

Exercises

These exercises help you practise writing briefs.

Press Check when you are ready. Use Show Hint if you get stuck.

What to Remember

• An orchestrator hands out work with briefs.
• A subagent knows only what the brief says.
• Every brief needs five parts: Goal, Inputs, Tools, Output and Done when.
• The answer must be data with exact fields, not a sentence.
• Field names must match exactly.
• Give only the tools the task needs.
• "Done when" should name a check that passes or fails.
• One brief, one task.

Further Reading

• Effective harnesses for long-running agents, by Anthropic: handing work between agents and sessions.
• Harness engineering, by OpenAI: structure that makes agent output usable.
• GitHub Spec Kit: tasks that can be handed out one by one.

Next: Spec Review. You will learn to review the agent's work against the spec, not against your own taste.