Agent Construction Best Practices

Build Principles

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

Use explicit names such as Fetch Open Vulnerabilities, Map Evidence to Controls, or Format Manager Summary.

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

Build one step, run it, validate output, then add the next step.

Start Simple

A reliable 2-step workflow is more valuable than an unstable 10-step workflow.

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

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

• 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

Caution

Do not promote workshop outputs directly to production without adding validation, ownership, and monitoring.

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

• Revisit Prompt Engineering Quick Reference
• Explore platform-level guidance in Creating and Managing Agents