A Reusable Agent Is a Contract, Not a Prompt

In TrueForge, the reusable unit is an agent definition: a named or inline contract that binds a model to instructions, tools, procedures, and runtime behavior. This chapter examines what that contract owns, what it merely references, and how the distinction helps a reader design an agent without turning a system prompt into a storage place for every credential and playbook. The practical result is a way to choose each resource by the job it performs and to know which decisions belong in the UI, the API, or the surrounding deployment.

The definition that can be reused

A saved agent and a conversation are different things. An agent says what kind of work should be done and which resources may be used. A session is a particular issue worked through with that agent; many sessions can use the same definition, and each session can contain multiple turns. If a customer-support agent is saved once, one session can handle a refund question while another handles a shipping question. The conversations should not share context merely because they share an agent definition.

That separation is the first reason to call the agent spec a contract. It is stable enough to reuse, but specific enough to constrain a runtime. The required core is a model reference. Around it, the definition can add focused instructions, named MCP servers, skills, and configuration for capabilities such as sandboxing, subagents, clarifying questions, and Generative UI. Through the API it can also specify model parameters, response format, seed messages, iteration limits, and context-management behavior. The saved definition is not a transcript and not a running process; it is the set of inputs from which each new session can be built.

The model reference answers which LLM should drive the loop. TrueForge’s model setup keeps provider credentials in shared configuration, so an agent can refer to a model by name without carrying an API key in every saved definition. This makes changing a provider credential an infrastructure operation rather than an edit to every agent. It also clarifies the limit of the abstraction: the agent chooses a model, but the model provider still determines the quality, availability, and provider-specific behavior of the calls.

Instructions are the agent’s role and constraints. They should explain what the assistant is for, who it serves, and how it should behave. They are not a convenient place to copy the documentation for every attached tool or to paste a long operational manual. TrueForge already supplies built-in guidance for enabled capabilities, and it exposes attached skills progressively. A focused instruction such as “look up order details before taking action and confirm before a refund” gives the model a behavioral boundary; the detailed escalation procedure belongs in a skill, where it can be loaded when relevant.

This distinction also separates decisions from defaults. The chat UI intentionally covers the choices most people need while composing an agent: model selection, instructions, connector attachment, connector preloading, skills, sandbox enablement, and a small set of capabilities. The API exposes the deeper contract when an application needs exact model parameters, tool filters, approval policy, iteration bounds, context-management switches, a response schema, or initial messages. That is not two different agent models. It is one contract with a simple authoring surface and a more complete programmatic surface.

classDiagram class AgentSpec { model reference instructions runtime configuration } class ModelProvider { credentials and model IDs } class MCPMount { enabled tools preload policy approval policy } class MCPServer { external actions and data } class SkillMount { procedure reference } class Sandbox { code and file execution } class Session { conversation context } AgentSpec *-- MCPMount : names AgentSpec *-- SkillMount : attaches AgentSpec --> ModelProvider : selects MCPMount --> MCPServer : reaches through SkillMount --> Sandbox : materializes in AgentSpec --> Sandbox : enables when needed AgentSpec --> Session : starts many

The contract’s value is not the number of fields it can hold. It is the way each field points to a different responsibility. A model reference selects a source of generation. Instructions establish role. An MCP mount grants a path to external action or data. A skill provides a procedure. Runtime configuration turns on mechanisms that affect how the loop manages context, interaction, and execution. A session then gives those choices a concrete conversation in which state can accumulate.

That separation is useful when an agent is changed. Suppose a support team wants the assistant to answer order-status questions but never process a refund without explicit confirmation. The model and the high-level instruction express the role. The connector mount names the order system and limits the available operations. The approval policy protects the refund operation. The session records the particular customer’s conversation. If the team later changes the provider credential or replaces the search endpoint, those changes can occur at the shared-resource layer; if it changes the support behavior, the agent definition can be revised; if one customer’s conversation needs to be corrected, the session is the relevant object. A contract is valuable because it gives each change a proper home.

The distinction also matters for reproducibility. A model name alone does not describe all of the runtime behavior: parameters may alter generation, a skill may change the procedure, a tool filter may remove an operation, and a sandbox setting may make file work possible. Conversely, a prompt alone does not record which external resources were attached or which policies narrowed them. A reader inspecting an agent needs the composition, not just the prose instructions. TrueForge’s agent spec is designed to hold that composition while leaving credentials and provider state outside it.

Named agents are consequently closer to reusable operational definitions than to saved chats. They can be selected by the UI or referenced by name through the SDK, and many sessions can start from the same baseline. An inline spec has a different lifecycle: it is suitable when an application wants a request-specific definition and does not need to add a shared entry to the registry. The choice between them is about ownership and reuse, not about whether the runtime becomes less capable.

The distinction between saved and inline agents reinforces this design. An application can save a spec under a unique name and let many sessions reference it, or pass a spec inline when it needs a one-off assistant without adding anything to the agent registry. The inline form is useful for an experiment or a request-specific configuration. The named form is useful when the definition itself is an operational asset that should be edited, reused, and discovered. Neither form changes the fact that the running session owns the conversation state.

Choose resources by function, not by label

The most important design choice is not whether a resource is called a tool, a skill, or a sandbox. It is what crosses the interface and who owns the next decision.

An MCP server is the action and data boundary. It can expose a lookup into a CRM, a search over documents, a ticketing operation, or a control over infrastructure. The agent does not embed the server’s credentials; it attaches the configured server by name. The server remains responsible for its external semantics, while TrueForge can narrow the tools exposed to this particular agent. A support agent might be given an order lookup and a refund operation, while a reporting agent receives only read-oriented queries from the same broader connector.

A skill is the procedure boundary. It is a git-backed directory rooted at SKILL.md, with optional references and scripts. The skill can explain an escalation path, a database-query method, or a release-note format. TrueForge initially exposes the skill’s name and description, then materializes the content in the sandbox when the agent decides it is relevant. This keeps a long playbook out of every model request and lets one procedure be reused across agents without making it part of each agent’s system prompt.

A sandbox is the computation and file boundary. It is where an enabled agent can run code, manipulate files, use bundled skill scripts, and produce artifacts. It is off by default and is required for skills and Code Mode. That dependency is meaningful: attaching a skill is not merely adding text to the prompt. It creates a runtime requirement for an environment in which the repository can be materialized and its supporting files can be used.

These resources can cooperate in one task. A web-research agent might use an MCP search server to obtain sources, a skill to define how findings should be organized, and a sandbox to build a self-contained brief. The contract does not say that each step must be performed by one mechanism. It says which mechanisms are available and allows the runtime to decide when to invoke them. That division keeps external access, specialized procedure, and local computation distinguishable when something goes wrong.

The shared setup behind these references is deliberately separate from the agent. TrueForge’s catalogs are discovery lists for model providers, MCP servers, skills, and sandbox providers. Selecting a catalog entry asks for the needed credentials or authorization, then stores the configured resource for later selection. A catalog can be customized by a self-hosted operator, and a resource can also be added outside the shipped list, such as a custom OpenAI-compatible model endpoint or an MCP server at another URL. The catalog helps people find a resource; the agent spec decides whether this agent uses it.

That separation has an operational payoff. If a connector’s API key changes, the resource configuration can be updated without copying a secret into agent instructions. If a model provider is replaced, agents can continue to refer to the configured model name or be switched deliberately. If a skill is used by several agents, its source and revision can be managed as a separate asset. These are useful forms of reuse, but they are not automatic trust. A configured connector can still expose unsafe or overpowered operations, a skill repository can contain unsafe instructions or scripts, and an external model or service can fail.

TrueForge gives an MCP mount several ways to narrow its meaning for one agent. Enable and disable selectors determine which tools are available. A preload choice determines whether definitions are loaded into context immediately or discovered later. An approval policy determines which calls must pause before execution. These controls do not change the external server; they create a per-agent view over it. That is an important architectural boundary: two agents can use the same registered connector with different exposure and interaction policies without duplicating the connector’s credentials.

The three controls answer different questions, so combining them carelessly can produce a misleading configuration. A tool can be enabled but deferred, which means the agent may call it after discovering its schema rather than seeing the definition at startup. A tool can be available but require approval, which preserves autonomy for ordinary work while stopping at a sensitive boundary. A server can be attached but have most of its tools disabled, which is different from attaching a smaller server with the same credentials. Preload controls context cost; enablement controls capability; approval controls execution timing. Treating these as one generic “access” switch makes it harder to predict the agent’s behavior.

The default policies are also a reason to inspect the external server’s annotations. TrueForge classifies tools marked read-only, write, or destructive and normally requires approval for write or destructive calls. That is a useful default for a well-described MCP server, but the annotation is supplied by the server. A tool whose description is incomplete or inaccurate may not receive the classification an operator expects. Literal tool names or an all-tools approval rule can make the policy more explicit when the consequences justify it. The harness provides the decision point; it cannot infer the business meaning of an unfamiliar external operation with certainty.

The same distinction applies to skills. A skill can tell an agent how to carry out a support escalation, but it does not grant the APIs needed to update a ticket. The MCP mount grants those actions, and the sandbox provides the place to run any supporting script. Keeping the procedure separate from the permission to act means the procedure can be reviewed or revised without silently expanding the tool surface. It also makes a failure easier to diagnose: if the agent knows the right procedure but cannot complete the task, the missing piece may be a connector or policy rather than an instruction problem.

The policies also show why an attached connector should not be described as unrestricted access. A server may publish many tools, but an agent can be limited to a read-only subset or a named list. Conversely, the default approval classification depends on the annotations published by the MCP server, so the harness cannot repair a misleading description of an external operation by itself. Exact approval behavior and the user experience of a pause become especially important when the agent can change real data; they deserve their own analysis rather than being hidden in a configuration tour.

The same logic applies to instructions. A prompt can state a role and a high-level constraint, but it should not silently become the only place where an organization stores governance. Tool exposure belongs to MCP policy, specialized procedures belong to skills, execution belongs to the sandbox, and human decisions belong to the turn protocol. Keeping those concerns separate makes the agent easier to inspect and gives the runtime a place to intervene.

A useful test is to ask what would need to change if the model stayed the same but the job changed. If the task needs a new data source, add or change an MCP mount. If it needs a reliable procedure, attach or revise a skill. If it needs deterministic aggregation or a file artifact, enable the sandbox. If it needs a different model behavior, change the model parameters or instructions. If it needs to protect a consequential action, define the approval policy and the client’s response handling. The agent spec becomes a map of these choices instead of a bag of prompt text.

Once that map is assembled, its meaning is no longer static. The next question is how TrueForge turns the contract into a running session: how a user message becomes a turn, how model and tool activity is recorded, and how the runtime decides whether to continue, pause, or finish.

References