agents-best-practices

Agents Best Practices

An agent harness is the control plane around a model. The model proposes; the harness validates, authorizes, executes, records, and returns observations.

Start With The Boundary

Identify:

• domain and user;
• autonomy level: answer-only, draft-only, approval-gated action, or autonomous within policy;
• risk level: read-only, internal write, external communication, financial, legal, healthcare, security, destructive, or privileged;
• state duration: single turn, session, resumable workflow, or long-running goal;
• tool surface;
• validation signal.

Minimal Harness Shape

task
  -> context builder
  -> model call
  -> proposed tool/action
  -> schema validation
  -> permission decision
  -> execution or approval pause
  -> structured observation
  -> state update
  -> finish or continue within budget

Harness Checklist

Before recommending implementation, cover these surfaces:

• agentic loop: turn budget, stop rules, loop detection, checkpoint/resume;
• tool registry: static vs dynamic tools, schema quality, denial/error shape, MCP boundaries;
• context assembly: priority order, just-in-time loading, compaction, source attribution;
• memory: session state vs durable memory, write policy, contradiction handling;
• guardrails: trust boundaries, prompt-injection exposure, sandbox/network/filesystem policy;
• permissions: read/write/send/delete/pay/deploy classes, approval gates, classifier-assisted routing only with deterministic backstops;
• observability: event log, tool outcomes, user-visible state, no hidden-reasoning leakage;
• evals: success fixtures, safety fixtures, eval noise budget, floor/ceiling checks;
• managed-agent architecture: separate brain, hands, credentials, session state, and worker lifecycle when the agent becomes long-running.

Design Rules

• Application code enforces safety; prompts only describe desired behavior.
• Every tool call returns a structured result, including denials and errors.
• Risky side effects require explicit policy and usually human approval.
• Draft and commit/send/pay/delete are separate actions.
• Tool schemas should be narrow, typed, validated, and auditable.
• Context should be tight, source-aware, and loaded just in time.
• Skills and connectors use progressive disclosure; do not expose every capability up front.
• Long-running goals need budgets, checkpoints, resumable state, and a measurable done condition.
• Observability records events and outcomes without exposing hidden reasoning.
• Sandboxes and permission gates belong in the harness, not in the agent's self-restraint.
• Treat classifier-based permission helpers as advisory unless a deterministic policy layer can still deny unsafe actions.