Agent Design Patterns

When to use which runtime, single vs multi-agent patterns

Agent Design Patterns

This guide covers common patterns for designing agents on the Enterprise Agentic AI Platform. It draws on real configurations from the platform's demo agents and the type system defined in packages/types/src/agent.ts.

Choosing an Execution Mode

The platform supports three execution modes (defined as the ExecutionMode type):

• platform-managed -- The platform handles the LLM loop, MCP tool calls, memory, and tracing. You configure a system prompt, model, and tool grants in Studio.
• external-procode -- Your own LangGraph, CrewAI, AutoGen, or Pydantic AI service handles inference. The platform forwards messages and enforces governance (guardrails, HITL, audit).
• external-n8n -- An n8n workflow receives the user message via webhook. Good for integration-heavy structured workflows.

Decision Matrix

When to Use Each Mode

Platform-Managed -- best for conversational agents whose logic fits within "system prompt + tool access":

• Customer Support Bot (agent-1): KB search + ticket creation + web search
• HR Onboarding Assistant (agent-hr-onboarding): KB search + ticket creation
• Finance Compliance Agent (agent-finance-compliance): KB search + database query

External Pro-Code -- best for complex reasoning, custom graphs, or multi-agent coordination:

• Research Pipeline (agent-research-pipeline): LangGraph multi-agent pipeline with topic decomposition
• Code Review (agent-autogen): AutoGen multi-agent reviewer (SAST + JSON validation + schema analysis)
• Support Ticket Crew (agent-crewai): CrewAI crew with HITL approval on ticket creation

External n8n -- best for integration-heavy workflows triggered by events or schedules:

• IT ticket creation via n8n workflow (tool-demo-n8n-ticket): structured webhook that creates tickets with SLA deadlines
• Data pipeline orchestration, scheduled reports, webhook-to-Slack routing

Single Agent Patterns

RAG Q&A Agent

The simplest and most common pattern: an agent that searches a knowledge base and answers questions with citations.

Platform example: Customer Support Bot (agent-1)

Execution Mode:  platform-managed
Tools:           tool-kb (Knowledge Base Search)
Model:           claude-sonnet-4 (primary), gpt-4.1-mini (fallback)
Temperature:     0.3 (factual)
Memory:          short-term + long-term (ttlDays: 30)
Knowledge:       kb-1, strategy: semantic, topK: 5, relevanceThreshold: 0.7
Guardrails:      input: pii-detection, prompt-injection
                 output: toxicity-filter, hallucination-check

Key design choices:

• Low temperature (0.3) keeps answers grounded in retrieved content.
• hallucination-check output guardrail catches unsupported claims.
• maxContextTokens: 2000 prevents overwhelming the prompt with retrieval results.
• Fallback model (gpt-4.1-mini) provides resilience if the primary is unavailable.

Support Triage Agent

Classifies incoming issues, searches for known solutions, and creates tickets for unresolved items. Requires write tool access with HITL gates.

Platform example: IT Help Desk (agent-demo-1)

Execution Mode:  platform-managed
Tools:           tool-kb, tool-web-search, tool-demo-n8n-ticket
Model:           claude-sonnet-4, fallback gpt-4.1-mini
Risk:            semi-autonomous
HITL:            disabled at agent level (per-tool approval on ticket creation)

The system prompt instructs the agent to follow a triage sequence:

1. Search the internal KB first for known solutions.
2. Fall back to web search if KB has no relevant answer.
3. Create a ticket only when the issue needs escalation or tracking.

The tool-demo-n8n-ticket tool uses the n8n bridge protocol (n8n://bridge/n8n-wf-demo-ticket), demonstrating cross-runtime tool composition: a pro-code agent calling an n8n workflow as an MCP tool.

Research Agent

Searches multiple sources, synthesizes findings, and produces structured summaries. Often uses iterative search-then-summarize loops.

Platform example: Research Analyst (agent-2)

Execution Mode:  platform-managed
Tools:           tool-web-search, tool-kb, tool-summarizer
Model:           claude-sonnet-4, maxTokens: 4096
Knowledge:       kb-1 + kb-2, strategy: hybrid, topK: 5
Memory:          short-term + long-term
Interaction:     canInvoke: agent-demo-1 (up to 5 delegations)

The system prompt defines a three-phase workflow: search KB for internal information, search the web for external sources, then combine and summarize with citations. The hybrid retrieval strategy uses both semantic and keyword search for broader coverage.

Multi-Agent Patterns

The platform supports five orchestration patterns (defined in packages/types/src/orchestration.ts as the OrchestrationPattern type).

Sequential Pipeline

One agent's output feeds the next. Tasks have explicit dependsOn relationships.

Pattern: 'sequential'
Flow:    Task A --> Task B --> Task C

Example: Contract review pipeline

1. Legal Contract Reviewer (agent-legal-reviewer) analyzes the document and flags risks.
2. Finance Compliance Agent (agent-finance-compliance) checks financial clauses for regulatory compliance.
3. A summarizer agent produces the final report.

This is configured through interactionPolicy:

// agent-legal-reviewer can invoke agent-finance-compliance
interactionPolicy: {
  canInvoke: [{ agentId: 'agent-finance-compliance', maxDelegationsPerExecution: 2 }],
  invocableBy: [],
  discoverable: false
}

The maxDelegationsPerExecution limit prevents runaway delegation chains.

Parallel Fan-Out

Multiple agents work on independent subtasks concurrently, and results are merged.

Pattern: 'parallel'
Flow:    [Task A, Task B, Task C] --> Merge

Example: Competitive analysis -- one agent researches the prospect (web search), another searches the product catalog KB, a third analyzes competitors. The orchestrator creates SubTask objects with empty dependsOn arrays so they run concurrently, then adds a final merge task that depends on all three.

Router Pattern

An LLM decides which single agent is best suited for the task, then routes the request.

Pattern: 'router'
Flow:    Classify --> Route to best agent

Example: A front-door agent classifies queries and routes to HR Onboarding Assistant, Finance Compliance Agent, IT Help Desk, or Sales Pipeline Assistant. The router uses a cheap model (gpt-4.1-mini) for classification. The discoverable: true flag on agents allows the router to find them.

Evaluator-Optimizer Loop

Execute a task, evaluate the quality, and refine until a threshold is met or max iterations are reached.

Pattern: 'evaluator_optimizer'
Flow:    Execute --> Evaluate --> (score < threshold?) --> Improve --> Evaluate --> ...

Example: Marketing content generation

1. Marketing Content Generator (agent-marketing-content) drafts copy.
2. An evaluator scores brand alignment, clarity, and engagement.
3. If below threshold, the generator revises with specific feedback.
4. Loop up to maxIterations times.

Configured via OrchestrationGoal.constraints:

constraints: {
  qualityThreshold: 0.85,
  maxIterations: 3,
  maxCostUsd: 1.00
}

The QualityEvaluation type tracks score, feedback, suggestions, and iteration number.

Orchestrator-Workers

A planner agent decomposes a goal into subtasks and assigns them to worker agents dynamically.

Pattern: 'orchestrator_workers'
Flow:    Plan --> [Worker A, Worker B, ...] --> Synthesize

Example: Research Pipeline (agent-research-pipeline) This external LangGraph agent implements an orchestrator-workers pattern internally:

1. A planner breaks the research topic into questions.
2. Multiple researcher workers search the web in parallel.
3. A synthesizer produces the final report with citations.

The platform tracks this via SubagentInstance with delegation depth tracking and resource budgets (tokenBudget, costBudget, timeoutMs).

Cross-Runtime Patterns

n8n as MCP Tool for Pro-Code Agents

A pro-code agent calls an n8n workflow as if it were any other MCP tool. The platform bridges the invocation through the n8n://bridge/ protocol.

Platform example: IT Help Desk (agent-demo-1) uses tool-demo-n8n-ticket:

{ id: 'tool-demo-n8n-ticket', mcpEndpoint: 'n8n://bridge/n8n-wf-demo-ticket' }

The n8n workflow handles the structured ticket creation logic (assigning priority, SLA deadlines, notification routing), while the pro-code agent handles the conversational triage.

Pro-Code as MCP Tool for n8n Workflows

An n8n workflow calls a pro-code agent via the AG-UI + A2A protocols. The n8n HTTP Request node sends a turn request to the agent's endpoint, and the response feeds into subsequent n8n nodes. Use this when a workflow needs LLM reasoning at a specific step (e.g., classify an incoming email before routing it).

Mixed Orchestration via Temporal

Each subtask in an OrchestrationPlan specifies a runtime preference (procode, n8n, or auto). The orchestrator runs each as a Temporal activity -- reasoning-heavy tasks route to pro-code agents; integration-heavy tasks route to n8n workflows.

Prototype-to-Promote

Start with n8n for rapid prototyping, then graduate to pro-code when you need more control:

1. Build and test the workflow visually in n8n.
2. Verify behavior with platform guardrails and tracing.
3. When the workflow needs custom state or multi-agent coordination, rewrite as external pro-code.
4. Keep the same agent ID and tool grants; change executionMode from external-n8n to external-procode.

Tool Composition Patterns

Read-Then-Write Chains

Search for information first, then take action based on the results. Separate tool grants enforce different permission levels.

Example: Customer Support Bot (agent-1)

• tool-kb has ['read', 'execute'] permissions (read-only search).
• tool-ticket has ['read', 'write', 'execute'] permissions with requireApproval: true.

The agent searches the KB for order status (safe, no approval needed), then creates a refund ticket (write action, requires HITL approval).

Fallback Chains

Use a primary tool, and fall back to a secondary if the primary produces no results. Encoded in the system prompt rather than declaratively.

Example: IT Help Desk search strategy

1. Search knowledge_base_search for internal documentation.
2. If KB returns no relevant results, search web_search for external solutions.
3. If neither produces a solution, create a ticket for manual investigation.

Model config supports the same pattern: primary: 'claude-sonnet-4', fallback: 'gpt-4.1-mini'.

Tool Sets (Reusable Bundles)

Group related tools into a named bundle that can be assigned to agents as a unit. Defined in packages/types/src/tool-set.ts.

Examples of natural tool sets from the demo agents:

• Research Bundle: tool-web-search + tool-kb + tool-summarizer (used by Research Analyst, Marketing Content Generator, Sales Pipeline Assistant)
• Developer Bundle: tool-sast + tool-json-validator + tool-db (used by Developer Assistant, Code Review)
• Support Bundle: tool-kb + tool-ticket (used by Customer Support Bot, HR Onboarding Assistant)

Tool sets simplify grant management: grant a set to an agent instead of granting each tool individually.

Error Handling and Resilience

Retry Strategies

The platform uses Temporal for durable execution, providing automatic retries with configurable policies:

• Exponential backoff for transient failures (LLM rate limits, network timeouts).
• Circuit breaker at the MCP Gateway: if a tool fails repeatedly, stop calling it and return a graceful error.
• Timeout enforcement: externalConfig.timeoutMs (default 30s for synchronous, 300s for streaming). The Research Pipeline sets timeoutMs: 120000 for long-running pipelines.

HITL Escalation for Uncertain Decisions

Configure HITL at two levels:

1. Agent-level: hitl.riskThreshold triggers approval when confidence drops below the threshold. Finance Compliance Agent uses 0.5; Legal Contract Reviewer uses 0.4 (more conservative).
2. Tool-level: toolGrants.conditions.requireApproval triggers approval before a specific tool executes. Customer Support Bot requires approval for tool-ticket but not tool-kb.

The approvalPolicy on tool grants specifies approverGroups (e.g., ['support-leads']) and allowSelfApproval.

Graceful Degradation

• Model fallback: agent-1 falls from claude-sonnet-4 to gpt-4.1-mini when the primary is unavailable.
• Tool fallback: KB returns nothing? Try web search. Both fail? Create a ticket.
• Runtime fallback: External endpoint unreachable (health check fails)? Route to a platform-managed backup.
• Budget exhaustion: SubagentInstance tracks costUsed vs costBudget. Status becomes budget_exhausted and execution stops gracefully.

Cost Optimization

Model Tiering

Use cheaper models for simple tasks and premium models only when quality matters.

Platform examples:

• Developer Assistant (agent-3): maxCostPerRequest: 0.10 (low cost for code scanning)
• Legal Contract Reviewer (agent-legal-reviewer): maxCostPerRequest: 1.00, maxCostPerDay: 50.00 (premium model budget for high-stakes reviews)
• HR Onboarding Assistant (agent-hr-onboarding): maxCostPerRequest: 0.30, maxCostPerDay: 15.00 (moderate budget for conversational Q&A)

Response Caching via Memory

Enable long-term memory (memory.longTerm: true) to avoid re-running the full tool chain for recurring questions. Control cache lifetime with ttlDays: Customer Support Bot uses 30 days; Legal Contract Reviewer uses 730 days for legal precedent. For frequently asked questions, procedural memory (memory.procedural: true) learns task patterns automatically.

Token Budget Enforcement

AgentModelAccess provides three levers: maxCostPerRequest (cap per LLM call), maxCostPerDay (daily ceiling), and maxTokensPerRequest (token limit per call).

For multi-agent orchestration, OrchestrationGoal.constraints.maxCostUsd caps the entire run. At the subagent level, SubagentResourceConfig provides per-child budgets:

subagentConfig: { tokenBudget: 10000, costBudget: 0.50, timeoutMs: 60000 }

Further Reading

• Platform-Managed Agents -- step-by-step guide for building no-code agents
• External Agents -- AG-UI + A2A protocol, supported formats, and framework examples
• Tool Integration -- registering custom MCP tools
• Knowledge Bases -- creating and populating knowledge bases
• Memory Configuration -- configuring the four memory types
• Eval Suite and Playground -- testing agents before deployment