Anvia Docs

AgentBuilder is the main entry point for creating an agent. It binds a completion model to instructions, context, tools, output rules, hooks, observers, and run defaults.

Minimal Agent

import { AgentBuilder } from "@anvia/core";
import { OpenAIClient } from "@anvia/openai";

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

const agent = new AgentBuilder("support", model)
  .name("Support Agent")
  .description("Answers product support questions.")
  .instructions("Answer clearly. Ask for missing details before guessing.")
  .build();

const response = await agent.prompt("How do I reset my password?").send();

console.log(response.output);

The first constructor argument is the stable agent id. Use an id that is safe to log, trace, and reference from other workflows.

Builder Shape

Most agents start with the same sequence:

Create a provider client.
Create a completion model.
Pass the model into AgentBuilder.
Add instructions, context, tools, and runtime defaults.
Call .build() once and reuse the agent.

const agent = new AgentBuilder("support", model)
  .instructions("You are a support assistant for Acme.")
  .context("Password reset links expire after 30 minutes.", "password-policy")
  .defaultMaxTurns(3)
  .build();

Common Builder Methods

Method	Use it for
`.name(...)`	Human-readable display name for dashboards and traces
`.description(...)`	Explain what the agent does, especially when exposed as a tool
`.instructions(...)`	Persistent behavior rules sent with every prompt
`.context(...)`	Small static facts included with every prompt
`.dynamicContext(...)`	Runtime retrieval from a vector index
`.tool(...)` / `.tools(...)`	Application actions the model may call
`.mcp(...)`	Tools from MCP servers
`.skills(...)`	Skill instructions and tools
`.outputSchema(...)`	Schema-constrained final output
`.defaultMaxTurns(...)`	Default tool-call loop limit
`.observe(...)`	Run, generation, tool, usage, and trace observers

Prompt the Agent

.prompt(...) creates a request. Chain request-level options before .send().

const history = await conversations.loadMessages(conversationId);

const response = await agent
  .prompt("What did we decide earlier?")
  .withHistory(history)
  .maxTurns(2)
  .withTrace({ name: "support-follow-up", userId: "user_123" })
  .send();

response.messages contains the new messages created by this run. Store those messages when you need the next prompt to continue the conversation.

Use an Agent as a Tool

Agents can be exposed to other agents as tools. This is useful when one agent owns a narrow workflow.

const refundAgent = new AgentBuilder("refunds", model)
  .description("Handles refund policy questions.")
  .instructions("Answer only refund-related questions.")
  .build();

const triageAgent = new AgentBuilder("triage", model)
  .instructions("Route refund questions to the refund agent.")
  .tool(
    refundAgent.asTool({
      name: "ask_refund_agent",
      maxTurns: 2,
    }),
  )
  .defaultMaxTurns(3)
  .build();

Keep nested agent tools narrow. A broad agent calling another broad agent is harder to debug than a focused delegation boundary.

Agent Builder

Minimal Agent

Builder Shape

Common Builder Methods

Prompt the Agent

Use an Agent as a Tool