Agent

The Agent runs the loop. It coordinates the Provider, the Scopes you register, history, and lifecycle hooks.

Usage

import { Agent, OpenAiProvider } from '@ag2b/core';

import { board } from './board';

const agent = new Agent({
  provider: new OpenAiProvider({ baseURL: '/api/llm', model: 'gpt-4o' }),
  system: 'You help users manage a kanban board.',
});

agent.scopes.register(board);

const response = await agent.chat('What is blocked right now?');
console.log(response.content);

createAgent

function createAgent(config: AgentConfig, scopes?: Scope[]): Agent

When your scopes already exist at construction time, the createAgent factory wires them in one call:

import { createAgent, OpenAiProvider } from '@ag2b/core';

import { board, calendar } from './scopes';

const agent = createAgent(
  {
    provider: new OpenAiProvider({ baseURL: '/api/llm', model: 'gpt-4o' }),
    system: 'You help users manage a kanban board.',
  },
  [board, calendar]
);

Configuration

provider

provider: AbstractProvider

Built-in OpenAiProvider, AnthropicProvider, or a custom provider you write.

The provider is the only thing in the runtime that talks to the network.

system

system: string | undefined

Base system prompt sent with every request. Scope contexts with injection: 'system' are appended after this base on each turn.

maxIterations

maxIterations: number | undefined

Maximum number of loop iterations before the agent gives up. Defaults to 20.

When the loop runs this many iterations without producing a final response, Ag2bMaxIterationsError fires.

Surface

The Agent's public surface:

• chat(message, options?) — drive the loop, await the final response.
• chatStream(message, signal?) — same loop, yields events as they happen.
• scopes — the scope registry.
• history — conversation history.
• addHook(event, fn) — observe or intercept any lifecycle event.
• use(plugin) — install a plugin — hooks, scopes, or any other agent setup bundled together.

Runtime Errors

Ag2bMaxIterationsError

Thrown when the iteration counter reaches maxIterations. Carries .iterations — the count reached.