Terminal Chat Example

Run the bundled streaming terminal chat example against OpenAI-compatible or OpenRouter providers.

packages/agents/examples/terminal-chat.ts is a minimal multi-turn CLI that streams assistant tokens with runAgentStream. It keeps in-memory history across turns and supports /help, /clear, /exit, and /quit.

Run it

cd packages/agents
OPENAI_API_KEY=... npm run example:chat

Defaults to OpenAICompatibleModel with OPENAI_MODEL falling back to gpt-4o-mini. Set OPENAI_BASE_URL for a local or proxy endpoint.

OpenRouter

AGENTS_PROVIDER=openrouter OPENROUTER_API_KEY=... npm run example:chat

OPENROUTER_MODEL defaults to openai/gpt-4o-mini.

Verbose usage

npm run example:chat -- --verbose
# or
AGENTS_CHAT_VERBOSE=1 npm run example:chat

Prints per-turn token usage (and cost when the provider reports it).

How streaming works

The example imports from @maniac-ai/agents and drives runAgentStream:

import {
  OpenAICompatibleModel,
  OpenRouterModel,
  runAgentStream,
  type AgentResult,
  type Message,
  type Model
} from "@maniac-ai/agents";

async function streamTurn(
  model: Model,
  query: string,
  history: Message[],
  verbose: boolean
): Promise<AgentResult<string>> {
  let result: AgentResult<string> | null = null;

  process.stdout.write("assistant > ");
  for await (const item of runAgentStream(
    {
      id: "terminal-chat",
      instructions: "You are a concise, helpful terminal chat assistant.",
      model
    },
    query,
    { prefixMessages: history }
  )) {
    if (
      item != null &&
      typeof item === "object" &&
      "kind" in item &&
      item.kind === "token" &&
      "chunk_kind" in item &&
      item.chunk_kind === "text" &&
      "delta" in item &&
      typeof item.delta === "string"
    ) {
      process.stdout.write(item.delta);
    }
    if ("final" in item) {
      result = item;
    }
  }

  process.stdout.write("\n");
  return result!;
}

Each turn appends non-system messages from result.messages to history. /clear resets that array while the process keeps running.

Provider selection

The example reads AGENTS_PROVIDER (or MANIAC_PROVIDER), defaulting to OpenAI-compatible:

function makeModel(): Model {
  const provider = (process.env.AGENTS_PROVIDER ?? "openai").toLowerCase();
  if (provider === "openrouter") {
    return new OpenRouterModel({
      slug: process.env.OPENROUTER_MODEL ?? "openai/gpt-4o-mini"
    });
  }
  return new OpenAICompatibleModel({
    slug: process.env.OPENAI_MODEL ?? "gpt-4o-mini",
    baseUrl: process.env.OPENAI_BASE_URL
  });
}

Help without a provider call

npm run example:chat -- --help

Verifies the CLI starts without contacting a model endpoint.