Agent Construction Best Practices
Build Principles
Section titled “Build Principles”One Job Per Step
Section titled “One Job Per Step”If one step analyzes, prioritizes, formats, and ticket-files all at once, split it. Steps should each have one primary responsibility.
Name Steps for Intent
Section titled “Name Steps for Intent”Use explicit names such as Fetch Open Vulnerabilities, Map Evidence to Controls, or Format Manager Summary.
Pick the Correct Step Type
Section titled “Pick the Correct Step Type”- LLM Step: reasoning, categorization, summarization
- Action Step: deterministic reads/writes in integrations
- API Action Step: direct external HTTP interaction
Test Incrementally
Section titled “Test Incrementally”Build one step, run it, validate output, then add the next step.
Start Simple
Section titled “Start Simple”A reliable 2-step workflow is more valuable than an unstable 10-step workflow.
Know When To Go Agentic
Section titled “Know When To Go Agentic”Use a single-step runbook with tool calling when the next action depends on what is discovered mid-run (for example, incident triage across multiple systems).
Design Pattern Comparison
Section titled “Design Pattern Comparison”| Pattern | Best For | Tradeoff |
|---|---|---|
| Procedural multi-step | Repeatable, fixed workflows | Less adaptive to unexpected findings |
| Agentic single-step | Dynamic investigations and branching decisions | Requires stronger prompt guardrails |
Production Hardening Checklist
Section titled “Production Hardening Checklist”- Add explicit output schema and severity/confidence scales
- Require evidence attribution for every major claim
- Define escalation criteria (for example, CRITICAL implies immediate notification)
- Add failure handling paths (missing data, integration timeout)
- Log and review representative runs before full rollout
Common Failure Modes and Fixes
Section titled “Common Failure Modes and Fixes”| Failure Mode | Why It Happens | Practical Fix |
|---|---|---|
| Overly broad or generic outputs | Prompt lacks structure and constraints | Add strict output schema and decision criteria |
| Inconsistent decisions across runs | Ambiguous thresholds | Encode explicit thresholds and tie-break rules |
| Missed evidence from integrated tools | Tool usage expectations are unclear | Require per-source evidence lines in final output |
| Unmaintainable workflows | Step intent is unclear | Rename and scope each step to one job |
Recommended Follow-Up
Section titled “Recommended Follow-Up”- Revisit Prompt Engineering Quick Reference
- Explore platform-level guidance in Creating and Managing Agents