Overview

The @talosjs/ai package lets you build agents: a model, a set of system prompts, the tools it can call, and the middleware that observes or shapes each run, all described by a small typed class. The base Chat class owns the agent loop (call the model, run the tools it asks for, feed the results back, repeat until done) and exposes two surfaces: run for a single result and stream for token-by-token events. Under the hood, agents run on TanStack AI with the OpenRouter adapter, so any provider/model available on OpenRouter is a one-line change.

What the package gives you

You subclass Chat, implement four getters, and the base class wires them into the agent loop. Agents, tools, and middleware are all registered with a decorator and resolved from the DI container, so their dependencies inject without extra plumbing. A tool’s input schema is an ArkType assertion, and arguments are validated before your handler runs. Middleware can observe or transform every stage of a run: config, chunks, tool calls, usage, and the terminal outcome. When you need data instead of prose, pass an output schema and the run returns a validated, typed object. And for common jobs there are ready-made tools for web search, encyclopedia, biomedical, and Linear lookups, so you don’t have to write those yourself.

The building blocks

Block	What it is	Page
Agent	A typed `Chat` subclass describing the model, system prompts, tools, and middleware.	Defining an Agent
Running	`run` for one result, `stream` for live events, with per-request input.	Running an Agent
Tools	Function-calling classes the model invokes, with validated typed input.	Tools
Middleware	Lifecycle hooks that observe or transform a run.	Middleware
Structured Output	A schema that turns the final answer into a typed object.	Structured Output
Built-in Tools	Web, Wikipedia, PubMed, and Linear tools you can add without writing code.	Built-in Tools

Installation

bun add @talosjs/ai

Models are reached through OpenRouter, so set your key in the environment:

OPENROUTER_API_KEY=sk-or-...

Quick example

Describe the agent as a class, register it with the decorator.chat() decorator, then resolve and run it from the container:

import { container } from "@talosjs/container";
import { Chat, decorator } from "@talosjs/ai";
import type { AiMiddlewareClassType, AiToolClassType } from "@talosjs/ai";

@decorator.chat()
class SupportChat extends Chat {
  public getModel = (): string => "anthropic/claude-sonnet-4.5";
  public getSystemPrompts = (): string[] => ["You are a concise support agent."];
  public getTools = (): AiToolClassType[] => [];
  public getMiddlewares = (): AiMiddlewareClassType[] => [];
}

const reply = await container.get(SupportChat).run<string>({ prompt: "Hi!" });

That is a complete agent. From here you can give it tools so it can search the web or act on your system, add middleware to audit, trace, or transform runs, and ask for structured output when you need a typed object back.

The model identifier is an OpenRouter provider/model string, e.g. anthropic/claude-sonnet-4.5, openai/gpt-5, or google/gemini-2.5-pro. Switch providers by changing that one line.

Getting Started

AI

Framework

Command Line

What the package gives you

The building blocks

Installation

Quick example

​What the package gives you

​The building blocks

​Installation

​Quick example

What the package gives you

The building blocks

Installation

Quick example