Build with an Agent

An Agent runs a model/tool conversation inside your application. Supply a model and instructions, expose validated application functions as tools, then inspect the terminal result. Use an Agent when the model should decide which tool to call next. Use a Workflow when your code defines the sequence. New project? Follow the quickstart for installation and a complete first run. This guide explains how to extend that application. Exact fields and signatures are in the Agent reference.

Run and inspect a result

Host function: pass a configured ModelProvider and the user’s input. The function owns and closes the Agent; selecting a live provider makes a network request using that provider’s credentials.

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

export async function answer(model: ModelProvider, input: string) {
  const agent = new Agent({
    name: "support", model, register: false,
    instructions: "Help with orders. Ask for an order ID when one is missing.",
  });
  try {
    const result = await agent.run(input);
    if (result.status !== "completed") {
      throw new Error(`Support run ended with ${result.status}`);
    }
    return { text: result.text, usage: result.usage, runId: result.runId };
  } finally {
    await agent.close();
  }
}

For an input such as “Where is my order?”, expect a request for an order ID. The exact wording varies. A completed run proves execution finished; it does not prove the answer is factually correct. Add a quality check for your application’s behavior.

Follow the model/tool loop

Agentium builds context from instructions, the input, and enabled state/context features.
The model returns an answer or requests a tool call.
Agentium validates arguments, applies execution controls, invokes the tool, and returns its result to the model.
Further model/tool rounds continue within the configured limits.
The terminal result contains text, status, usage, and any structured output.

run() waits for the result. stream() emits typed chunks as the run progresses. A session groups conversation turns; it is not a durable job or proof of the caller’s identity.

Choose the next capability

You need to…	Add	Verify
Read or change application data	A validated tool	Its returned record or confirmed effect, not just the model’s claim
Return a value to application code	Structured output	The validated `structured` result
Continue a conversation	Session memory	A follow-up uses the earlier fact for the same owner
Answer from documents	Retrieval	Retrieved source IDs and answer grounding
Show progress to a client	Streaming	Text chunks, terminal status, and disconnect cleanup
Require a decision before an effect	Approval	Denial prevents the selected tool from executing
Add project context	Workspace and skills	Only the selected directory and instructions are exposed
Share controls around multiple capabilities	@agentium/harness	Grants, budgets, policy decisions, and resource lifecycle

Pass identity and context per run

run(input, options) accepts session/user/tenant identifiers, cancellation, metadata, and execution services. Your host supplies verified identity and authorizes access to application records. IDs supplied by a caller are not authentication. Use stable, owner-scoped session IDs with configured memory and storage. For a request-specific dependency, use runtime dependencies. For time limits and cancellation, see cancellation. A long-lived service can reuse an Agent and close it when its owner shuts down. The small function above instead creates one per invocation. Decide who owns shared stores and clients before choosing a lifetime.

Handle results and streams

Read status before treating an output as successful. Use text for display, structured for schema-backed values, usage for reported tokens, and runId for correlation. Consult RunOutput for the exact contract. For streaming, branch on each chunk’s type before reading its fields. See the streaming tutorial for a complete consumer and events for run/tool observations. Event listeners observe execution; loop hooks and execution policy control it.

Configure limits and lifetime

Bound tool rounds, model output, cancellation, and admission concurrency for the workload. These controls apply at different boundaries: a token budget does not cap every external service effect, and a checkpoint does not undo a tool call. Use cost accounting, context compaction, and tool-result limits as needed. Close the Agent after its runs settle, then drain observers/exporters owned by the host. See operations.

More patterns

Agent patterns: sessions, streams, project context, and events.
Tools and approvals: typed application boundaries and ownership.
Lifecycle patterns: hooks, cancellation, dependencies, and snapshots.
Agent API: generated declarations for configuration, run options, results, and methods.

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

Build with an Agent

Run and inspect a result

Follow the model/tool loop

Choose the next capability

Pass identity and context per run

Handle results and streams

Configure limits and lifetime

More patterns

​Run and inspect a result

​Follow the model/tool loop

​Choose the next capability

​Pass identity and context per run

​Handle results and streams

​Configure limits and lifetime

​More patterns

Run and inspect a result

Follow the model/tool loop

Choose the next capability

Pass identity and context per run

Handle results and streams

Configure limits and lifetime

More patterns