Agent Design Fundamentals

Operating procedure for deciding whether a workflow needs an agent at all, and for architecting it if so: single-agent loop first, multi-agent only on measured failure; manager pattern vs decentralized handoffs; three tool types; layered guardrails; explicit human-intervention triggers. Distilled from OpenAI's 34-page "A Practical Guide to Building Agents" (April 2025).

When to use

Use this skill when you are:

• Deciding whether a workflow should be an agent, a simpler LLM app, or deterministic code.
• Designing a new agent's architecture: model choice, tool set, instructions, orchestration.
• Deciding whether to split one agent into several, or which multi-agent pattern to use.
• Adding guardrails or human-in-the-loop escalation to an agent before production.

Do NOT use this skill for:

• Apps that merely integrate an LLM without letting it control workflow execution — simple chatbots, single-turn LLMs, sentiment classifiers. Per the source, these are not agents.
• Workflows that deterministic, rule-based automation already handles cleanly — the source says a deterministic solution may suffice; do not agentify them.

Rules

Gate: should this be an agent at all?

1. Define the target as a workflow — the sequence of steps that has to be carried out to reach the user's goal. An agent is a system that "independently accomplish[es] tasks on your behalf" (OpenAI): it uses an LLM to manage workflow execution, recognizes completion, corrects its own actions, halts and returns control to the user on failure, and dynamically selects tools within guardrails.
2. Build an agent only if the workflow clearly meets at least one of these three criteria; otherwise ship deterministic code:
   • Complex decision-making: nuanced judgment, exceptions, context-sensitive decisions (e.g., refund approval in customer service).
   • Difficult-to-maintain rules: rulesets so extensive and intricate that updates are costly or error-prone (e.g., vendor security reviews).
   • Heavy reliance on unstructured data: interpreting natural language, extracting meaning from documents, conversational interaction (e.g., processing a home insurance claim).

Foundations: model, tools, instructions

3. Compose every agent from exactly three core components: a model (reasoning/decision-making), tools (external functions or APIs), and instructions (explicit guidelines and guardrails defining behavior).
4. Prototype with the most capable model on every task to establish a performance baseline, then swap in smaller/faster models where they still hit the accuracy target. Order of operations: (1) set up evals for a baseline, (2) meet your accuracy target with the best models, (3) optimize cost and latency by downgrading models where possible. Never prematurely limit the agent by starting small — you lose the ability to diagnose where small models fail. Simple retrieval or intent classification can run on a smaller model; decisions like refund approval warrant a more capable one.
5. Give each tool a standardized, well-documented, tested, reusable definition, enabling many-to-many relationships between tools and agents. Provide all three tool types the workflow needs:
   • Data tools to retrieve context (query databases/CRMs, read PDFs, search the web).
   • Action tools to change state (send emails/texts, update a CRM record, hand off a ticket to a human).
   • Orchestration tools — other agents used as tools (refund agent, research agent, writing agent). For legacy systems without APIs, use computer-use models to operate their UIs directly, as a human would.
6. Write instructions from existing operating procedures, support scripts, and policy documents (in customer service, roughly one routine per knowledge-base article). Break dense material into smaller, clearer steps. Make every step correspond to a specific action or output — even the exact wording of a user-facing message. Capture edge cases with conditional steps/branches (e.g., an alternative step when required info is missing). You may use an advanced reasoning model (the source names o1 or o3-mini) to auto-convert policy documents into numbered agent instructions.

Orchestration: single agent first

7. Start with a single agent running in a loop until an exit condition: a final-output tool call, a response without tool calls, an error, or a maximum number of turns. Add capability by incrementally adding tools — this keeps complexity manageable and simplifies evaluation and maintenance.
8. Before adding agents, exhaust prompt templates: one flexible base prompt that accepts policy variables (e.g., {{user_first_name}}, {{user_tenure}}, {{user_complaint_categories}}). Update variables for new use cases instead of rewriting workflows.
9. Maximize a single agent's capabilities first. Split into multiple agents only when the agent fails to follow complicated instructions or consistently selects wrong tools, and only on these concrete signals:
   • Complex logic: prompts with many if-then-else branches whose templates no longer scale — divide each logical segment into a separate agent.
   • Tool overload: the problem is similarity/overlap, not count — some implementations manage more than 15 well-defined, distinct tools while others struggle with fewer than 10 overlapping ones. Only split after descriptive names, clear parameters, and detailed descriptions have failed to fix performance.

Multi-agent: choose the pattern by control needs

10. Use the manager pattern (agents as tools) when exactly one agent should control workflow execution and own the user relationship: a central manager LLM calls specialized agents as tools (e.g., spanish_agent.as_tool(tool_name=..., tool_description=...)), delegates tasks, and synthesizes results into one cohesive answer. Model it as a graph where edges are tool calls.
11. Use the decentralized pattern (handoffs) when no single agent needs central control or synthesis: peer agents transfer execution one-way via handoff, passing the latest conversation state, and the receiving agent takes over the user interaction (e.g., a triage agent with handoffs=[technical_support_agent, sales_assistant_agent, order_management_agent]). Optimal for conversation triage and full task takeover; optionally give the second agent a handoff back. Edges in the graph are handoffs.
12. Whichever pattern you pick, keep components flexible and composable, and drive them with clear, well-structured prompts. Prefer code-first orchestration over declarative graph DSLs when workflows are dynamic — pre-defining every branch, loop, and conditional gets cumbersome as complexity grows.

Guardrails: layered defense

13. Never rely on a single guardrail — layer multiple specialized ones: LLM-based classifiers, rules-based checks (regex, blocklists, input length limits), and a moderation API together. Deploy the types the source enumerates as risks demand:
    • Relevance classifier — flags off-topic queries outside the agent's intended scope.
    • Safety classifier — detects jailbreaks and prompt injections trying to extract system prompts or exploit the system.
    • PII filter — vets model output for personally identifiable information.
    • Moderation — flags hate speech, harassment, violence.
    • Tool safeguards — rate every tool low/medium/high risk based on read-only vs. write access, reversibility, required account permissions, and financial impact; use ratings to pause for checks before high-risk functions or escalate to a human.
    • Rules-based protections — blocklists, input length limits, regex filters against known threats like prohibited terms or SQL injection.
    • Output validation — prompt engineering and content checks for brand-aligned responses.
14. Build guardrails in this order: (1) cover data privacy and content safety first, (2) add new guardrails from real-world edge cases and failures you actually encounter, (3) tune for both security and user experience as the agent evolves. Run guardrails concurrently with the primary agent (optimistic execution), raising an exception/tripwire on breach rather than serializing every check.
15. Treat guardrails as a complement to — not a substitute for — authentication and authorization, strict access controls, and standard software security measures.

Human in the loop

16. Plan for human intervention from the start; it is especially important early in deployment for finding failures and edge cases. The source identifies two primary triggers for human escalation:
    • Exceeding failure thresholds — set limits on retries or actions; escalate when exceeded (e.g., the agent fails to understand customer intent after multiple attempts).
    • High-risk actions — sensitive, irreversible, or high-stakes operations (canceling user orders, authorizing large refunds, making payments) require human oversight until confidence in the agent's reliability grows.
17. On escalation, transfer control gracefully: in customer service, hand the issue to a human agent; for a coding agent, hand control back to the user.

Checklist

Before building:

• Workflow named and decomposed into steps toward the user's goal.
• At least one build criterion clearly met: complex decision-making / difficult-to-maintain rules / heavy unstructured data. If none — ship deterministic code instead.

Design:

• Evals set up; baseline established with the most capable model before any downgrade.
• Each tool typed (data / action / orchestration), standardized, documented, tested, reusable.
• Instructions derived from existing SOPs/policies; every step maps to a specific action or output; edge cases have conditional branches.

Orchestration:

• Started as a single agent in a loop with defined exit conditions (final-output tool, no-tool-call response, error, max turns).
• Prompt templates with policy variables tried before adding agents.
• Split justified only by observed failures (instruction-following breaks or wrong tool selection), not anticipation.
• Pattern chosen deliberately: manager (one agent controls + synthesizes) vs decentralized (peers hand off and take over the user).

Safety:

• Multiple guardrail layers: relevance + safety classifiers, PII filter, moderation, rules-based checks, output validation.
• Every tool risk-rated low/medium/high (write access, reversibility, permissions, financial impact); high-risk tools gated.
• Failure thresholds (retry/action limits) defined with human escalation wired up.
• High-risk actions (cancellations, large refunds, payments) require human oversight.
• Auth, access controls, and standard software security in place independent of guardrails.

Anti-patterns

• Calling a simple chatbot, single-turn LLM app, or classifier an "agent" — if the LLM doesn't control workflow execution, it isn't one.
• Building an agent for a workflow that clean deterministic rules already solve.
• Jumping straight to a fully autonomous multi-agent architecture — the source reports customers achieve greater success incrementally, single agent first.
• Starting with small models to save cost before establishing a baseline — you can't diagnose where they fail.
• Splitting agents to fix tool confusion before trying descriptive names, clear parameters, and detailed descriptions.
• Counting tools instead of measuring overlap — >15 distinct tools can work while <10 overlapping ones fail.
• Relying on a single guardrail instead of layered defenses; or using guardrails as a substitute for authentication, authorization, and access controls.
• Letting an agent execute sensitive, irreversible, or high-stakes actions (order cancellation, large refunds, payments) without human oversight before its reliability is proven.
• Shipping without failure thresholds, so a stuck agent retries forever instead of escalating to a human.

Source

• A Practical Guide to Building Agents (OpenAI, PDF) — https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf — 2025-04

Distilled from the official document(s) above on 2026-08-12. If this skill and the source disagree, trust the source.