Agent Systems

Why

Tool-using systems can cross the boundary from generating text to changing state. That expands usefulness and risk at the same time.

Mental Model

An agent is a controlled loop: observe → decide → act → verify. The model proposes; the harness owns state, permissions, execution, and stopping.

Core Concepts

• Tool contracts and typed arguments
• Working state and durable state
• Planning horizons and stop conditions
• Permission boundaries and approvals
• Idempotency and compensating actions
• Sandboxing and untrusted tool output

How It Works

The orchestrator gives the model a task, relevant state, and tool definitions. The model selects an action. The harness validates arguments and authorization, executes the tool, records the outcome, and returns an observation. The cycle ends on success, failure, budget exhaustion, or a required human decision.

In Harness

Every loop iteration becomes a trace span with decision, tool input fingerprint, permission result, output summary, state delta, and budget consumption.

Engineering

Keep tools narrow and composable. Separate read from write capabilities. Require idempotency keys for retriable mutations. Bound steps, time, tokens, and spend. Verify completion from external state rather than model narration.

Trade-offs

More autonomy reduces coordination cost but increases blast radius. General tools are flexible but harder to secure. Long planning horizons can solve larger tasks while compounding early errors.

Common Mistakes

• Letting generated text directly become a shell or database command.
• Retrying a mutation without idempotency.
• Trusting tool output as instructions.
• Using one broad credential for unrelated capabilities.

Practice

Implement a three-tool loop with one read, one reversible write, and one verification tool. Inject timeouts, malformed outputs, duplicate calls, and permission denial.

Sources

See the reference library for tool-use, security, and distributed-systems references.