Anvia Docs

@anvia/core is the central package. Every other @anvia/* package depends on it. It provides the agent runtime, tool system, message types, pipeline execution, structured extraction, evals, vector store interfaces, memory, MCP adapters, and observability contracts.

Install

pnpm add @anvia/core

Pair it with a provider package to get a model:

pnpm add @anvia/openai

Quick Start

import { AgentBuilder, createTool } from "@anvia/core";
import { OpenAIClient } from "@anvia/openai";
import { z } from "zod";

const client = new OpenAIClient({ apiKey });
const model = client.completionModel("gpt-5.5");

const lookupOrder = createTool({
  name: "lookup_order",
  description: "Look up an order by id.",
  input: z.object({ orderId: z.string() }),
  output: z.object({ status: z.string() }),
  async execute({ orderId }) {
    return { status: orderId === "A-100" ? "shipped" : "unknown" };
  },
});

const agent = new AgentBuilder("support", model)
  .name("Support Agent")
  .instructions("Answer support questions. Use tools when needed.")
  .tool(lookupOrder)
  .defaultMaxTurns(3)
  .build();

const response = await agent.prompt("Where is order A-100?").send();
console.log(response.output);

Root Exports

The root import path covers the most common APIs:

import {
  AgentBuilder,
  createTool,
  Message,
  // ...and many more
} from "@anvia/core";

Use the root import for small apps, examples, and prototyping.

Subpath Exports

For larger codebases or narrower dependency boundaries, import from focused subpaths:

Subpath	Area
`@anvia/core/agent`	Agent builders, hooks, run controls, errors, run events
`@anvia/core/completion`	Completion messages, requests, responses, usage, model contracts
`@anvia/core/tool`	Tool definitions, registries, tool sets, serialization
`@anvia/core/pipeline`	Typed pipelines and batch execution
`@anvia/core/extractor`	Structured extraction builders
`@anvia/core/evals`	Eval suites, metrics, agent targets, reporters
`@anvia/core/embeddings`	Embedding models, documents, vector math
`@anvia/core/vector-store`	In-memory vector store, filters, search tools
`@anvia/core/memory`	Durable session memory interfaces
`@anvia/core/mcp`	MCP connection helpers and normalized types
`@anvia/core/observability`	Observer interfaces, trace options, score contracts
`@anvia/core/skills`	Skill loading, discovery, validation
`@anvia/core/streaming`	Async iterable to ReadableStream conversion
`@anvia/core/loaders`	Node file and PDF loaders
`@anvia/core/model-listing`	Provider-neutral model listing contracts
`@anvia/core/image-generation`	Image generation contracts
`@anvia/core/audio-generation`	Audio generation contracts
`@anvia/core/transcription`	Audio transcription contracts

import { AgentBuilder } from "@anvia/core/agent";
import { createTool } from "@anvia/core/tool";
import type { CompletionModel } from "@anvia/core/completion";

@anvia/core/loaders is intentionally subpath-only so that normal core imports do not pull in Node filesystem and PDF dependencies.

Key Concepts

AgentBuilder is the primary entry point. It configures an agent with a model, instructions, tools, context, observers, and hooks, then .build() produces a reusable agent.

createTool defines a tool with Zod-validated input and output schemas. Tools are pure TypeScript functions that the agent can call during a run.

Messages are plain objects (Message.user(...), Message.assistant(...), Message.tool(...)). History is a Message[] array you store wherever your app persists conversations.

Observers receive lifecycle events (run start/end, generation, tool calls) without changing runtime behavior. Attach them with .observe(...).

Hooks can cancel runs, approve tool calls, or transform requests and responses. Attach them with .onRunStart(...), .onToolCall(...), etc.

When to Use Subpaths

Start with root imports while learning. Move to subpaths when:

You want explicit import boundaries between modules
Your bundler benefits from tree-shaking narrower entry points
You are building an integration package that only needs tool types, not the full agent runtime

Getting Started for a step-by-step first agent
SDK Fundamentals for runtime architecture
Core Reference for full API types