Prompt Engineering Patterns for Orchestrator Agents

The Routing Pattern: Directing Agent Behavior

Orchestrator agents often need to decide between multiple execution paths. Rather than building complex conditional logic in your application layer, embed routing decisions directly into your prompt.

Use a structured prompt that asks Claude to classify incoming requests into predefined categories, then return a JSON decision object. This keeps agent logic auditable and reduces backend branching.

The key is providing clear category definitions with examples. Give Claude 2-3 real examples of what each route looks like, and it will generalize accurately to new inputs.

const routingPrompt = `You are an agent router. Classify the user request into ONE category.

Categories:
- search: factual queries requiring real-time data
- database: questions answerable from stored data
- analysis: requests needing computation or synthesis

Respond with JSON: {"route": "search|database|analysis", "confidence": 0.0-1.0, "reasoning": "brief explanation"}

User request: ${userMessage}`;

Context Window Management for Long Workflows

Long agent workflows consume tokens rapidly. Instead of accumulating full conversation history, implement a summarization pattern where completed steps are condensed into structured summaries.

After each agent step, generate a one-sentence JSON summary of what was accomplished. Pass only recent context (last 2-3 steps) plus the full summaries forward.

This pattern keeps token usage predictable and prevents context thrashing. For a typical 10-step workflow, you'll use 30-40% fewer tokens than naive history accumulation.

Decision Trees via Nested Prompts

Complex decisions don't fit in a single prompt. Instead, structure agent logic as a sequence of focused, single-responsibility prompts where each one handles a discrete decision.

Have the first prompt classify the scenario, the second prompt evaluate constraints based on that classification, and the third prompt synthesize a decision. Each prompt can be optimized independently.

This pattern is easier to test, debug, and monitor than monolithic prompts. You can inject different models at different decision points based on cost/latency requirements.

Error Handling and Fallback Patterns

Production agents fail. Rather than letting failures propagate, build explicit fallback prompts into your workflow. If a search step fails, immediately route to a fallback step that uses cached or approximate data.

Include a 'confidence' field in all Claude responses. If confidence falls below your threshold (0.6-0.7 depending on context), trigger a fallback path automatically.

Use structured error states: each fallback should return the same JSON shape as the primary path, so downstream steps don't need to handle conditional logic.

Function Calling for Deterministic Outputs

Don't rely on Claude's natural language when you need deterministic structured data. Use the function calling API to force Claude into specific schemas.

Define tools for each meaningful action: search, database_query, update_record, send_notification. Claude treats these as constrained outputs rather than suggestions.

This is especially critical in orchestrator agents where downstream steps depend on consistent, parseable responses. A malformed JSON response can derail an entire workflow.

Monitoring and Observability Patterns

Every prompt in your orchestrator should include internal logging signals. Ask Claude to include a 'reasoning' field explaining its decision, even when it's not part of the final output.

Log these reasoning traces alongside token counts and latency metrics. Over time, you'll identify which patterns are reliable and which need refinement.

Use structured logging (JSON events, not strings) so you can aggregate patterns across your agent fleet and catch systemic issues early.

Open-source implementation

Everything in this article runs in pantheon — a production-ready Next.js + Supabase + Claude starter. Clone it, deploy to Vercel, run PM2. The dashboard auto-commits every agent edit and reverts itself if TypeScript breaks.