Agents

An agent combines a model, instructions and tools. Call generate for a complete response or stream to stream tokens. The tool-calling loop runs for you.

Defining an agent

agent.ts

import { Agent } from '@redtuma/core/agent'

const agent = new Agent({
  id: 'assistant',
  name: 'Assistant',
  instructions: 'You are concise and helpful.',
  model: 'anthropic/claude-opus-4-8',
  tools: { /* ... */ },
})

model is a 'provider/model' string, an AI SDK LanguageModel, or a tiered routing policy.

generate

Returns the text plus tool calls, usage, finish reason and the raw response.

const res = await agent.generate('What is the weather in Taipei?')

res.text         // the model's answer
res.toolCalls    // tools the model invoked
res.usage        // { promptTokens, completionTokens, totalTokens }
res.finishReason

stream

const result = await agent.stream('Tell me a short story.')
for await (const chunk of result.textStream) {
  process.stdout.write(chunk)
}

Structured output

Pass a Zod schema as output to get a validated object back.

import { z } from 'zod'

const res = await agent.generate('Extract the city and temp.', {
  output: z.object({ city: z.string(), tempC: z.number() }),
})

res.object // { city: 'Taipei', tempC: 30 }

Dynamic instructions

Instructions can be a function of the per-call runtime context.

const agent = new Agent({
  id: 'greeter',
  instructions: ({ runtimeContext }) =>
    `Greet the user by name: ${runtimeContext.get('name') ?? 'there'}.`,
  model: 'anthropic/claude-opus-4-8',
})

The Redtuma registry

import { Redtuma } from '@redtuma/core'

const redtuma = new Redtuma({ agents: { assistant: agent } })
redtuma.getAgent('assistant')

Give an agent memory to persist conversations, or wire tools so it can take actions.

← Quickstart Tools →