Designing Main-Agent System Prompts: A Practical Blueprint

Why the Main-Agent Prompt Sets the Ceiling

In enterprise coding assistants and knowledge Q&A, quality is rarely decided by a single model call. It is decided by the system prompt of the main agent. That prompt defines identity boundaries, how the agent thinks, when to split work, how to call internal tools, and how the final answer should be structured. A loose prompt leads to free expansion, repeated retrieval, and missed constraints. An overly rigid one fails on long-tail questions. This article breaks the main-agent prompt into implementable modules and a reusable way to organize them. It is not tied to any vendor model. The same principles apply to general large-model orchestration and internal toolchains.

1. Persona and Goals: Set Boundaries Before Capabilities

The opening of the main-agent prompt should state three things: role, audience, and success criteria.

• Role: for example, “an enterprise engineering assistant that prefers actionable technical options and explicit risks,” not a vague “do-everything assistant.”
• Audience: engineering, operations, and data analysis teams differ in how dense terminology should be and how much evidence they expect.
• Success criteria: answers must be actionable, verifiable, and grounded in internal knowledge. When something is unknown, say so. Do not invent API names or performance numbers.

Write goals as checkable clauses. Examples: prefer authorized internal search and code search; treat public web information with caution; any production change must include a rollback idea. If the persona conflicts with tool permissions—for instance, the persona says “change the database freely” while tools are read-only—instructions will fight each other at runtime. That conflict is a common source of production incidents.

2. Research Process: A Four-Step Thinking Loop

A fixed loop is more useful than slogans about “thinking before acting.” Use four steps: assessment and decomposition, query-type classification, a plan for that type, and execution.

2.1 Step 1: Assessment and Decomposition

After receiving the question, judge whether known information is enough, whether hidden constraints exist (environment, permissions, compliance), and whether the task is single-hop or multi-hop. Split the question into atomic sub-questions. “Find why this API failed” might become: confirm the error code, compare recent releases, check dependency configuration, and propose verification steps. Keep the decomposition in an internal draft (collapsible for the user) so later steps do not drift.

2.2 Step 2: Query-Type Classification

Place the question in a small set of types so strategy can change with the type. Examples: factual lookup, code location, option comparison, incident troubleshooting, process handling, and creative draft. The type decides whether retrieval is needed, whether sub-agents are needed, and whether the answer is a short conclusion or a long structured piece. Misclassification is expensive: treating “change this configuration” as “write an essay” wastes the context window.

2.3 Step 3: Plan from the Classification

For that type, write the smallest workable plan: which tools, in what order, and what to do if a step fails. Include a stop condition, such as “after two retrieval rounds with no authoritative source, report uncertainty and list the gaps.” For long tasks, set stage milestones so constraints are not forgotten mid-plan.

2.4 Step 4: Execution

Call tools according to the plan, collect evidence, and cross-check it. If the classification was wrong, return to step 2, but record why, so the loop cannot run forever. Before finishing, self-check: did the answer address the original question, did it introduce unverified numbers, and did it expose sensitive internal paths?

3. Force Deployment: How Many Sub-Agents

Sub-agents are useful when independent sub-questions can be explored in parallel, such as searching a document store and a code repository at the same time. Suggested limits:

• Simple facts: zero sub-agents; the main agent answers directly.
• Two-source verification: one or two, each covering a different knowledge domain.
• Complex troubleshooting: no more than three or four. Beyond that, merging cost and conflicting conclusions rise quickly.

Each sub-agent needs a narrow goal, a clear input and output format, a timeout, and a failure return. The main agent arbitrates conflicts; it does not simply concatenate answers. In an enterprise setting, also limit each sub-agent’s tool permissions so it cannot perform unauthorized writes.

4. Delegation: Assign Slices, Not the Raw Question

Delegation is not forwarding the original question unchanged. It is issuing a task slice. A sound delegation instruction includes a short background, constraints that must be followed, the expected output structure, and prohibitions (for example, do not guess secrets, do not invent APIs). Split by data domain, not by sentence, so each sub-task can be finished in one context. When results come back, require source identifiers so the main agent can build an evidence chain.

5. Answer Format: Make Downstream Systems Able to Parse It

Formats for people and for systems should be specified separately. For people: lead with the conclusion, number the steps, and put risks in their own section. For systems: use structured fields such as status, evidence, and next action. A stable format cuts the cost of later processing. For complex proposals, fix the sections: problem understanding, key assumptions, steps, verification method, rollback, and monitoring. Do not drop unexplained internal codes into the body.

6. Advanced Use of Internal Tools

Internal tools typically include knowledge retrieval, code search, ticket lookup, read-only log and monitoring interfaces, and object-storage metadata queries. The prompt should state:

• When a call is mandatory: if the answer depends on versions, configuration, or live state, do not answer from memory.
• Preparation before the call: turn natural language into precise query terms and bound the time range and environment.
• How to use results: cited snippets must be traceable; conflicting evidence should be listed side by side.
• Prohibitions: do not request unauthorized write APIs; do not put full secrets or personal data into the final answer.

Describe capability boundaries, not marketing language. For example: “log search covers only a recent window of days and filters by service name.” That reduces hallucinations about capabilities that do not exist.

7. Parallel Tool Calls

Independent read-only queries should run in parallel to shorten end-to-end latency. Typical patterns: search documents and code symbol definitions together; fetch error-code explanations and recent change records together. Parallelism requires no write dependency and no ordered side effects. When there is a dependency, stay serial—for example, resolve the service name before querying that service’s logs. A useful heuristic for the prompt: if both sides are read-only and share no input, run them in parallel; if either result would change the other’s query, run them in series. When merging parallel results, deduplicate and mark source weight.

8. Seven Core Rules

1. If unsure, retrieve. If retrieval finds nothing, state the gap.
2. Do not invent API names, parameters, performance numbers, or billing rules.
3. Prefer internal authoritative sources. Use external information only as a supplement, and label it.
4. Least privilege: default to read-only. Writes need explicit confirmation.
5. Advance one main goal at a time. Do not let the topic drift.
6. Make the output verifiable: give a check-command idea or verification steps in neutral terms, without tying them to a specific third-party command brand.
7. Safety and compliance: do not assist attacks, do not output exploit details, and do not disclose unpublished internal implementation.

How to Roll This Out, and Common Failure Modes

Turn the modules above into a version-controlled prompt template. Tune the persona by business line, but keep the four-step loop and the seven rules the same. Review with replay of real tickets: look for wrong classification, over-delegation, and missing stop conditions. Common failures include too many sub-agents producing conflicting conclusions, parallel writes causing races, unstable answer formats that break downstream parsing, and a persona that is so “helpful” it exceeds its permissions. A small evaluation set covering factual questions, troubleshooting, and design proposals is more effective than simply making the prompt longer.

A main-agent prompt encodes organizational process into model context. When assessment, classification, planning, execution, tools, and format form a closed loop, the agent can produce reviewable results in an enterprise environment. The same emphasis on permissions and evidence applies when the agent uses general cloud capabilities such as object storage, logging, monitoring and alerting, and container platforms—do not just stack product names. Iterating the prompt along this structure usually lowers hallucination rate and average handling latency, and makes it possible for several people to maintain the prompt together.