agents-best-practices

---
name: agents-best-practices
description: Design, audit, or improve agentic systems and agent harnesses. Use for agent MVP blueprints, tool design, permission models, planning and goal loops, context compaction, memory, skills, connectors, observability, evals, safety, and provider-neutral agent architecture.
license: MIT
metadata:
  abvx_status: experimental
  abvx_origin: adapted
---

# 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

```text
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
```

## 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.

## MVP Blueprint Output

When asked to design an agent, produce:

- objective and MVP boundary;
- autonomy and risk model;
- core loop;
- instruction architecture;
- tool registry and permissions;
- context, memory, retrieval, and compaction;
- skills/connectors;
- safety and approvals;
- observability and evals;
- minimal implementation path.

Avoid multi-agent systems until a single-agent harness has measurable failure cases that require decomposition.