Skip to main content
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

Create the Agent once, then call it with each input. Install @agentium/core and openai, and set OPENAI_API_KEY. This example makes a paid model request.
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

  1. Agentium builds context from instructions, the input, and enabled state/context features.
  2. The model returns an answer or requests a tool call.
  3. Agentium validates arguments, applies execution controls, invokes the tool, and returns its result to the model.
  4. Further model/tool rounds continue within the configured limits.
  5. 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

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 the Agent across requests and close it when the service shuts down. Supplied accounting trackers and stores remain caller-owned.

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, costs for enabled accounting, 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