Tools, APIs, and the Harness

An agent is not just a model with a long prompt. It is a model operating inside an environment that assembles instructions, retrieves context, exposes tools, manages sessions, enforces permissions, coordinates workers, captures events, and decides when the run stops. That surrounding environment is the harness.

This distinction matters because many apparent intelligence failures are environmental. The model edited the wrong project because the workspace map was unclear. It repeated a tool call because the run had no idempotency record. It lost the goal because context compaction removed the acceptance criteria. Changing the model may hide the symptom without repairing the system.

A practical harness has layers for workspace identity, instruction assembly, model configuration, context management, tool access, execution state, memory, delegation, approvals, verification, and telemetry. Each layer should have an owner, interface, and failure signal.

Keep stable workspace facts—canonical repositories, schemas, policies, and commands—discoverable without pasting everything into every run. Keep full transcripts available for audit while giving the active worker a refined working context. Restrict tools before their definitions reach the model whenever possible.

A tool performs an action. A skill packages instructions and supporting resources for a recurring class of work. A meta-tool discovers, selects, composes, or creates other capabilities. These abstractions increase leverage and risk at the same time: a skill can make good practice repeatable, while a tool-discovery system can expose power the original task never needed.

Prefer small, typed, meaningful operations over a single universal executor. Make tool descriptions concrete enough for correct selection. Return structured results and error classes. Separate read from write. Scope credentials by service, account, operation, and duration. When a skill changes behavior, version it and evaluate it like any other production dependency.

A harness acts like a control system. Guides shape behavior before action: instructions, templates, schemas, policies, examples, plans, types, and permission filters. Sensors observe what happened: tool results, tests, validators, logs, graders, budgets, timeouts, and environmental checks.

Both can be deterministic or model-assisted. A schema validator is a deterministic sensor. A reviewer agent assessing whether a draft answers the brief is inferential. Use deterministic mechanisms for invariants and model judgment for semantics. The loop becomes reliable when observations can change the next action or stop the run.

Start with the smallest environment that already solves the infrastructure you do not want to own. An IDE assistant helps with local, supervised changes. A coding harness such as Codex or Claude Code adds repository navigation, tools, and execution loops. An agent framework such as an Agents SDK, ADK, or graph runtime helps build a product workflow. A workspace manager coordinates multiple projects or workers. A persistent personal runtime adds long-lived state, scheduling, and local integrations.

A framework gives primitives; a harness supplies operating defaults. A raw library may offer freedom but leave you responsible for sessions, permissions, retries, observability, and recovery. Choose from the time horizon, number of workers, security boundary, integration needs, and trajectory volume—not from the length of the feature list.

When a run fails, classify the first broken layer: task definition, prompt, model, context, tool, state, permission, orchestration, verification, or delivery. Capture the trajectory and the environment version. Repair the owning layer so the class of error becomes harder to repeat.

Prompt patches are appropriate for instruction failures. Missing repository identity belongs in workspace context. Repeated destructive commands need idempotency and policy. Lost work needs persisted state. Fake completion needs stronger receipts. Harness engineering is the discipline of turning observed failures into improved defaults.

More tools can reduce reliability. Large inventories consume context, create ambiguous choices, widen the attack surface, and make permission review difficult. Multiple uncoordinated agent windows can create the appearance of parallel progress while producing conflicting artifacts and hidden integration work.

Load capabilities progressively. Expose the smallest set required for the current task, retrieve specialized tools when needed, and record why each was selected. Parallelize only work with separate ownership and a defined integration step.