Runtime control patterns

Add a control when you can name the behavior it changes and how to verify it. These patterns assume you already have a working Agent. Use complete projects for initial setup.

Bound a request owned by your host

Host function: the caller owns an Agent and supplies input plus a deadline in milliseconds. The function returns a successful result or fails; it does not close an Agent that may serve other requests.

import { Agent } from "@agentium/core";

export async function answerWithin(agent: Agent, input: string, timeoutMs: number) {
  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
    throw new Error("timeoutMs must be a positive integer");
  }
  const result = await agent.run(input, { signal: AbortSignal.timeout(timeoutMs) });
  if (result.status !== "completed") throw new Error(`Run ended with ${result.status}`);
  return result;
}

Test this with a deliberately slow local fixture and verify the caller handles the unsuccessful outcome. Cancellation requests that work stop; it cannot retract an external effect already accepted by a service. For connection-owned work, use the transport’s disconnect lifecycle.

Keep a model/tool run bounded

Host factory: this gives each model call an output limit and bounds the Agent’s tool rounds. The caller supplies configured tools/model and owns the returned Agent.

import { Agent, type ModelProvider, type ToolDef } from "@agentium/core";

export function createBoundedAgent(model: ModelProvider, tools: ToolDef[]) {
  return new Agent({
    name: "bounded-support", model, tools, register: false,
    maxTokens: 512,
    maxToolRoundtrips: 4,
    instructions: "Answer concisely using the available evidence.",
  });
}

Output tokens, tool rounds, request deadline, concurrency, and aggregate harness budgets constrain different things. Pick values from the task and observed behavior; these example values are not universal service defaults. Close the Agent after its runs settle.

Select controls by the problem

Problem	Capability	Observable check
Need to inspect or change a loop decision	Loop hooks	A chosen hook changes the intended round/tool action
Conversation exceeds the working context	Context compaction	Required facts remain while context shrinks
Tool results consume too much context	Tool-result handling	Retained result still contains the evidence needed
An action needs operator review	Approval workflow project	Denial performs zero submissions
Selected sensitive fields must be scrubbed	PII guard	Test the configured patterns and their limitations
Need an explicit snapshot/fork	Checkpointing	Restore the intended state; do not assume effects roll back
Tools differ by caller or request	Dynamic tools	Tool list and underlying data access match verified identity
Need reusable instructions	Skills	The intended skill is discovered and applied
Similar requests may reuse answers	Semantic cache	Scope, invalidation, and similarity avoid stale or cross-user answers
A client needs capability discovery	Discovery cards	Only intended entities/capabilities are exposed
Need runtime telemetry	Quality gate with traces, metrics export	Report/trace/metric reaches the selected sink
Another service needs an event	Webhooks	Receiver confirms delivery; retry policy is understood
Work starts later or outside the request	Scheduling, queue jobs	Job identity, result, retry behavior, and drain are visible

Compose controls in a meaningful order

Start with one task and a quality assertion. Add request identity and tool authorization, then the limits required by its execution. Add telemetry so you can see denied, failed, canceled, and completed work. Finally, choose persistence and recovery for the failure you actually need to survive. A checkpoint, queue retry, cache hit, and durable task are different contracts. Use recovery design before combining them around an external action. Prefer a harness when shared abilities and controls need a reusable composition boundary.

More patterns

Use lifecycle patterns for hooks and dependencies, cost patterns for usage estimates, security patterns for host integration, and operations for admission and shutdown.

Complete projects

Agents & memory

Models & Jev

Tools & knowledge

Teams & jobs

Deploy & devices

Quality & production

Runtime control patterns

Bound a request owned by your host

Keep a model/tool run bounded

Select controls by the problem

Compose controls in a meaningful order

More patterns

​Bound a request owned by your host

​Keep a model/tool run bounded

​Select controls by the problem

​Compose controls in a meaningful order

​More patterns

Bound a request owned by your host

Keep a model/tool run bounded

Select controls by the problem

Compose controls in a meaningful order

More patterns