Source: https://anchor-sdk.dev/philosophy.html Package: anchor-ai-sdk@0.1.7 + THE THINKING BEHIND THE HARNESS # Let the model reason. Make the work real. An agent is more than a prompt and a loop. It needs a place to act, a way to carry what it learns, and boundaries that mean something when the work gets complicated. This is the philosophy behind Anchor: reusable execution mechanics, without quietly taking ownership of your application's judgment. A visual reading guideReviewed for SDK 0.1.7 **The model**reasons about the task THE HARNESS ContextActionObservation ↳ make the next turn informed, not isolated ↵ WorkspaceStateContinuity A mental model of the harness—not a live execution trace. THE PREMISE ## Build the behavior once. Stop rebuilding the machinery. Anchor grew out of building Sailor, an issue-to-PR agent. The same concerns kept turning up around the interesting part of the work: assembling context, executing tools, observing results, keeping a workspace, recording a journal, and deciding how another turn could continue. Those mechanics should not have to be rebuilt for every new agent. But extracting them should not turn a coding application's assumptions into rules for every consumer. A chat assistant, a research thread, and a repository agent can share an engine without sharing a personality, a database, or a publication policy. That tension is the starting point: **make the runtime more capable without making the application less explicit.** 01 ## Compose the agent. Don't fork the runtime. Behavior and capabilities should be data the engine can execute—not a new class hierarchy or a second loop. A strategy describes instructions, meaningful phases, and startup requirements. Tools pair a model-visible schema with a handler. An agent bundles the two. The host supplies the live model client and the resources needed for this execution. BEHAVIOR**Prompt + phases**AgentStrategy + CAPABILITIES**Schema + handler**Tool\[\] REUSABLE BUNDLE**Agent**strategy + tools add live dependencies when you run taskllmagentoptions**runAgent**result + events The bundle describes what the agent is. The run supplies the model, optional machine, state, and execution controls. This is why the built-in agents are bundles, not modes. Swapping a prompt or curating a tool set should not require copying the engine. A sandbox-free assistant can use the same loop as a machine-backed coding agent; their capabilities differ, not the fundamental execution model. **The practical consequence:** put reusable behavior in the agent and environment-specific choices in the run. Keep credentials, storage, and application services explicit. ### 02 ## Phases are a compass, not a conveyor belt. A useful approach is not the same thing as a mandatory itinerary. Investigating a bug, explaining a file, and reviewing a proposed change need different paths. Forcing all of them through reproduce → edit → verify can turn a reasonable answer into an artificial retry loop. Anchor lets the agent choose its next action from the observations it actually has. understandactvalidaterespond A coding task might inspect the failure, act, run a check, and explain what happened. Illustrative paths through an approach. These controls explain the idea; they do not run an agent or define legal transitions. Phases make the work legible. They give the prompt a vocabulary and the application a progress signal. They can be skipped or revisited, and finishing does not require reaching a final phase. That flexibility does not remove real boundaries: the host still chooses tools, budgets, cancellation, and publication policy. **The practical consequence:** use phase goals to guide reasoning. Use application code—not a phase label—to enforce an approval, permission, or release gate. ### 03 ## Give actions a shared place to happen. A coherent execution environment is more useful than a collection of unrelated command wrappers. When a tool reads a file, runs a command, or records a check, its result should describe the environment the next tool will work in. The sandbox contract gives machine-backed tools that shared place: a workspace, scratch storage, command execution, and supported lifecycle operations. bashread\_filerun\_tests **One shared execution environment** WORKSPACE`repository files``.anchor/notes.md`agent-authored notes, not automatic memory SCRATCH & EXECUTION`tool-output artifacts``deadline-bound commands`results the next turn can inspect Sandbox contract≠identical provider guarantees Machine tools share context through a sandbox. API-only agents need not have one; a local sandbox is not an isolation boundary. The provider seam keeps machine choice out of agent behavior. It does not pretend a local process, a container, and a remote microVM have identical guarantees. Capabilities such as retention, fork, and egress control must be declared and tested, not inferred from an adapter's name. **The practical consequence:** choose the toolchain, backend, permissions, and cleanup policy deliberately. “Sandbox-first” is an execution model, not a claim that every backend is a security boundary. ### 04 ## Retain more. Replay less. What the system keeps and what the model sees now are different questions. A context window is a working surface, not a universal archive. Replaying every old response and every oversized tool result makes that surface harder to use. Anchor separates bounded model context, persisted conversation, and workspace artifacts so each can do its own job. WHAT THE MODEL SEES NOW #### Working context Task, current instructions, recent observations, and a summary of earlier turns. bounded replay · compaction CONVERSATION CONTINUITY #### Thread state Stored conversation and runtime facts, with the summary and phase supplied by the run. load / persist with ThreadStore A PLACE TO RETURN TO #### Workspace artifacts Notes the agent writes, files it changes, and full-output spills when they succeed. read files · retain / checkpoint These are different stores of information, not three names for a bigger prompt. Their persistence depends on the adapters and lifecycle you configure. Compaction summarizes older conversation; it does not rewrite the agent's notes. A tool can leave a short observation and a pointer to a larger output artifact. A supplied thread store carries conversation into a later run. These mechanisms complement one another, but none makes the others unnecessary. **The practical consequence:** design for retrieval and re-entry, not just a larger prompt. Decide what must survive, where it lives, and how a resumed agent can find it. **The limits are part of the design.** Summaries are lossy. Notes must be written by the agent. Output spill is bounded and best-effort. In-memory stores are not crash-durable, and a failed checkpoint is not a backup. Choose and observe the persistence path your application actually needs. ### 05 ## Continue at honest boundaries. A task can outlive a turn, a command, or a worker. The system must be clear about which boundary it is crossing. New information should not corrupt an in-flight assistant/tool exchange. A queued message leaves the active run untouched. An interjection requests a switch at a safe boundary. Once an inbox store exposes the pending work, the engine can own chaining instead of making every application write its own abort-and-restart wrapper. ONE runAgent CALL · SHARED ALLOWANCE CURRENT TASK**Run A** safe boundary CLAIMED INBOX BATCH**Run B** A pending command can travel with the chain call returns **The next wake-up belongs to the host** Persist state and pendingJobs; restore the machine; supply resumeJobs when another worker calls the engine. Schematic, not a promise that every batch runs: cancellation, errors, pause, exhausted allowance, and the chain's safeguards can stop continuation. The same separation applies to background commands. A participating tool and polling-capable provider can detach work; Anchor polls and delivers the result during the call and carries pending jobs through an inbox chain. Interjecting is not the same as killing that command or undoing its writes. After the call returns, the clock belongs to the host again. A worker has to be woken, persisted state restored, the appropriate machine adopted, and remaining job handles handed back. An interface enables that continuity; it does not create a durable scheduler or exactly-once delivery by itself. **The practical consequence:** let the engine own deterministic timing within its call. Give your application explicit responsibility for storage, leases, idempotency, wake-up, and cleanup outside it. ### 06 ## Completion is an outcome. Trust is a decision. Record what happened without pretending it proves more than it does. A final answer can be valid without a test run: sometimes the task was to explain something. A successful runtime outcome should not secretly mean “verified” or “publish this.” Anchor records tool evidence independently, allowing an application to make a separate decision at a consequential boundary. #### “I'm done.” A final response or finish call can end the run. `reason: "finished"` ≠ #### Permission to publish A decision about authority, trusted checks, and acceptable risk. application policy **Evidence is an input to that decision.** Tool status, command outcome, and an optional post-run tree hash—not a correctness certificate. The engine can record what happened without claiming that it proves what your application needs. For a coding application, that decision might consider a trusted test command, its exit status, the current tree, permissions, and checks outside the agent. A post-run tree hash can help detect a later change. It is not an immutable snapshot of the bytes executed, and it does not cover ignored files, external inputs, or the meaning of the assertions. Observability follows the same philosophy. Trace entries can record model and tool events, but reasoning only exists when the provider reports it, pattern redaction is not complete secret detection, and a background-completion event is not an archive of the entire output. Unknown pricing is not a measured zero bill. **The practical consequence:** keep evidence inspectable and side-effect policy explicit. Do not infer permission to ship from confident prose, a phase transition, or result.ok. ### 07 ## Bound the work. Preserve the handoff. Autonomy is more useful when it has an explicit stopping condition. Repeated tool calls, empty turns, and a capped response are ordinary failure modes, not reasons to create an infinite outer retry loop. Anchor can offer bounded course correction while keeping spend, cancellation, and execution deadlines visible. THE MODEL GETS ROOM TO REASON attemptobservationadjust **Inside explicit limits**turns · usage · command deadlines · cancellation **Preserve a handoff**then let the application choose: continue, pause, or escalate Corrections are bounded assistance. Revival records remaining work; it does not authorize a new allowance. A command's detach threshold and its hard lifetime are different controls. A run's allowance and the provider's per-call output cap are different controls too. Usage is checked between model turns, so the last call can overshoot a run budget. A well-designed harness should expose those distinctions rather than hide them behind a single “keep trying” switch. When work remains, an agent can leave a revival handoff. That preserves the opportunity to continue without authorizing another purchase of tokens. The host decides whether the next step is a funded run, a pause, or a person. ### THE SEAM THAT TIES IT TOGETHER ## Anchor owns the mechanics. You own the judgment. Generic does not mean making the host do everything. It means taking ownership where the contract is clear, and refusing to smuggle application-specific decisions into the runtime. Where the responsibility belongs Concern Anchor supplies Your application decides Behavior Strategy, tool, and agent contracts Instructions, tools, domain rules, and authorization Execution The model/tool loop and lifecycle hooks Model, provider, toolchain, limits, and permitted actions Memory Compaction, thread interfaces, and spill mechanisms Durable adapters, retention, access, and backup policy Delivery Safe-boundary inbox chaining and in-call job polling Producer authentication, ownership, leases, and later wake-up Recovery Snapshots, handles, pending jobs, and revival handoffs Restore, re-funding, idempotency, cleanup, and escalation Trust Events, tool metadata, and evidence helpers Trusted checks and whether anything may be published The goal is not an agent that can never fail. It is a system whose behavior you can compose, whose work you can inspect, and whose next step you still control. TURN THE IDEAS INTO CODE ## Now build the agent. Start with the primitives, assemble the harness, then add the capabilities the task actually needs. [Build from primitives](https://anchor-sdk.dev/docs.html#primitives) [Read the complete harness](https://anchor-sdk.dev/docs.html#assembled) [Follow the decision log](https://github.com/hrithikkoduri/anchor-ai-sdk/blob/main/DECISIONS.md) **A source-backed explanation, not a new guarantee.** This guide describes the public 0.1.7 contract and the reasoning recorded in the SDK's decisions. Older decision entries include superseded designs; current implementation and the versioned API take precedence. Diagrams are conceptual. No live model or cloud sandbox is run by this page.