@anvia/core API reference

Core exposes common authoring APIs from @anvia/core and larger contracts from capability-specific subpaths. Application code should not import @anvia/core/internal/*; those entry points exist for Anvia integration packages.

Agents

Import from @anvia/core or @anvia/core/agent.

const agent = new Agent({
  id: 'support',
  model,
  name: 'Support agent',
  description: 'Answers account questions.',
  instructions: 'Use tools for account facts.',
  context: [staticDocument, contextIndex],
  tools: [lookupAccount, toolIndex],
  mcpServers: [mcpServer],
  skills,
  temperature: 0.2,
  maxTokens: 800,
  maxTurns: 5,
  toolChoice: 'auto',
  outputSchema,
  lifecycle,
  observability: { observers: { default: observer } },
  guardrails: policy,
  middlewares: [middleware],
  memory: { store: memoryStore },
})

Important methods:

agent.generate(options): Promise<AgentOutcome<Output>>
agent.resume(continuation, response, settings?): Promise<AgentOutcome<Output>>
agent.stream(options): AgentStream<Output, RawResponse>
agent.compactMemory({ session, abortSignal? }): Promise<MemoryCompactionResult>
agent.asTool(options): Tool

Run options include maxTurns, retries, abortSignal, lifecycle, guardrails, toolConcurrency, middlewares, controls, and trace.

AgentOutcome is a discriminated union. All branches share runId, text, usage, messages, and optional finish, context, trace, guardrail, source, provider-tool, memory-compaction, and resume metadata:

type AgentOutcome<Output> =
  | {
      type: 'response'
      output: Output
    }
  | {
      type: 'blocked'
      stage: 'input' | 'output'
      reason: string
      message?: string
    }
  | {
      type: 'interaction'
      interaction: AgentInteractionRequest
      continuation: AgentContinuation
    }

AgentStream is an async iterable of AgentStreamEvent. Its final emitted item is an AgentOutcome, not a wrapped final event. The handle also exposes events, textStream, text: Promise<string>, result: Promise<AgentOutcome<Output>>, steer(input), and cancel(reason?). Consume only one iterable surface per stream.

Pass session: { sessionId, userId?, metadata? } with a prompt to load and persist memory for that run. Use the configured store's load({ scope }) and clear({ scope }) methods for authorized inspection and deletion.

Use createVectorContext({ store, model, topK, minScore?, filter?, format? }) to register prompt-time vector retrieval in an agent's context array.

Set trace.promptRef on generate() or stream() to identify the prompt used by a run. The contract is { name: string; version?: number }; completion-request middleware can override it per generation or clear it with null.

Agent teams

Import from @anvia/core or @anvia/core/agent. See the Agent teams guide for behavior and production boundaries.

const team = new AgentTeam({
  id: 'research-team',
  model,
  instructions: 'Delegate research, review it, answer.',
  members: [researcher, reviewer],
  communication: { siblings: false },
  spawning: [{ from: researcher, to: [researcher] }],
  limits: {
    maxDepth: 3,
    maxConcurrentAgents: 4,
    maxAgentInstances: 12,
    maxTotalTurns: 100,
    maxBufferedEvents: 1024,
  },
})

Important methods and handles:

team.generate(options): Promise<AgentTeamOutcome<Output>>
team.stream(options): AgentTeamStream<Output>

Run options take exactly one of prompt or messages, plus ordinary agent run settings (except toolConcurrency) and an optional resolveInteraction(request: AgentTeamInteraction).

The runtime injects reserved coordination tools — spawn_<member.id>, send_message, wait_for_agent, list_agents, and cancel_agent (spawn-permitted instances only). Configured member tools must not use these names, and member IDs must form valid spawn tool names (1–58 letters, digits, underscores, or hyphens).

AgentTeamOutcome extends the Agent outcome union with teamRunId, aggregate usage, and a members array of AgentTeamMemberSummary (instanceId, agentId, name, parentInstanceId?, depth, status, usage, outcome or error). AgentTeamStream mirrors AgentStream with events, textStream, text, result, steer(input), and cancel(reason?), emitting AgentTeamEvents attributed with teamRunId and instanceId.

Errors: AgentTeamLimitError (turn budget, event buffer overflow) and AgentTeamInteractionError (missing or failing interaction resolver).

Direct completions

Import from @anvia/core or @anvia/core/completion.

const result = await generateCompletion({
    prompt: input,
    model,
    instructions,
    documents,
    tools,
    temperature,
    maxTokens,
    toolChoice,
    outputSchema,
    providerOptions,
    retries
})

Pass exactly one of prompt or messages. The result contains typed output, visible text, normalized assistant content, usage, and rawResponse.

const result = await generateCompletion({
    prompt: input,
    model,
    outputSchema: schema
})

console.log(result.output)

generateCompletion converts the outputSchema to provider JSON Schema (Zod natively, Valibot via the optional @valibot/to-json-schema peer, other Standard Schema libraries via ~standard.jsonSchema), parses the returned JSON, and validates it locally through ~standard.validate. Core also exports StandardSchemaV1, StandardJSONSchemaV1, and isStandardSchema.

for await (const event of streamCompletion({
    prompt: input,
    model
})) {
  if (event.type === 'text_delta') process.stdout.write(event.delta)
}

CompletionModel, StreamingCompletionModel, CompletionRequest, CompletionResponse, CompletionStreamEvent, capability types, message types, tool-call content, usage, and JSON value types are exported from the completion subpath.

Messages are strict JSON-safe structural objects. Core exports role/content types plus parseMessage, parseMessages, messageSchema, and messagesSchema for runtime validation.

Tools

Import from @anvia/core or @anvia/core/tool.

const tool = createTool({
  name: 'lookup_order',
  description: 'Look up one authorized order.',
  inputSchema: z.object({ orderId: z.string() }),
  outputSchema: z.object({
    orderId: z.string(),
    status: z.string(),
  }),
  requiresApproval: ({ orderId }) => ({
    reason: `Review access to ${orderId}.`,
  }),
  async execute(input, context) {
    return orders.lookup(input.orderId, context)
  },
})

inputSchema always validates arguments before execution. outputSchema is optional; when present, it validates and types the handler result. requiresApproval accepts a boolean, { reason? }, or a callback returning one of those values or false.

Create a semantic tool catalog with:

const index = await createToolIndex({
    model: embeddingModel,
    tools: tools,
    topK: 4,
    minScore: 0.72,
    filter,
    content,
    metadata,
    concurrency: 2
});

Pass the returned ToolIndex directly in Agent.tools. embedTools(...) returns embedded tool documents without constructing an index. isToolIndex(...) identifies the public catalog type.

createMiddleware(...) preserves middleware callbacks for completion requests, completion responses, tool input, and tool output. createThinkTool(...) creates a model-visible scratch tool.

Tool approval

Generated runs return type: 'interaction' before a guarded tool executes:

const pending = await agent.generate({
    prompt: input
})

if (pending.type === 'interaction' && pending.interaction.type === 'tool-approval') {
  const result = await agent.resume(
    pending.continuation,
    {
      type: 'tool-approval',
      approved: reviewer.approved,
      reason: reviewer.reason,
    },
  )
}

The continuation must return to the originating agent. Approval is orchestration; authorization still belongs in the tool handler. createQuestionTool({ name, description }) creates the other first-class interaction boundary for structured free-text or choice questions.

Guardrails and lifecycle

@anvia/core/guardrails exports defineGuardrailPolicy, defineInputGuardrail, defineOutputGuardrail, and built-in factories under guardrails.

Input and output guardrails can allow, block, or rewrite at their supported boundary. GuardrailPolicyInput can be configured on the agent and supplemented for one run.

An AgentLifecycle can implement:

const lifecycle = {
  onStart(event) {},
  onStepFinish(event) {},
  onToolStart(event) {},
  onToolFinish(event) {},
  onFinish(event) {},
  onError(event) {},
}

Lifecycle callbacks observe stable run boundaries. They are not an authorization substitute and do not replace requiresApproval.

Memory

Import contracts from @anvia/core/memory.

interface MemoryStore {
  readonly inspector?: MemoryInspector
  readonly compaction?: MemoryCompactionCapability
  load(options: { scope: MemoryScope }): Promise<Message[]>
  append(options: MemoryAppendOptions): Promise<void>
  clear(options: { scope: MemoryScope }): Promise<void>
  recordError?(options: MemoryErrorOptions): Promise<void>
}

The subpath also exports memory options, scope types, inspector contracts, compaction contracts, createSummaryMemoryCompactor, isMemoryCompactionMessage, and compaction errors.

MemoryStore.load() returns canonical replayable history. MemoryCompactionCapability.snapshot() returns the model-context projection: canonical history before compaction, then the latest summary checkpoint plus the unsummarized tail. replacePrefix() advances that checkpoint atomically and must not delete or overwrite canonical messages.

Token-aware compaction uses trigger.afterTokens, optional retention.recentTurns (default 1), an optional sync or async tokenCounter, and a compactor. Deprecated retention.recentTokens remains available as a mutually exclusive migration path. Core exports estimateMemoryTokens as the default provider-neutral estimate. MemoryCompactionInfo records original, compacted, retained, and result token/message counts, attempts, and summary-model usage. agent.compactMemory({ session }) forces an eligible prefix compaction and returns type: 'compacted' or type: 'skipped'.

Embeddings and vector stores

@anvia/core/embeddings exports:

const { embedding } = await embedText({ model, text })
const { embeddings } = await embedTexts({ model, texts })
const { embedding: sparseQuery } = await embedSparseQuery({ model: sparseModel, query })
const { embeddings: sparse } = await embedSparseTexts({ model: sparseModel, texts })
const { documents: denseDocuments } = await embedDocuments({
  model,
  documents,
  id,
  content,
  metadata,
})
const { documents: hybridDocuments } = await embedDocuments({
  models: { dense: model, sparse: sparseModel },
  documents,
  id,
  content,
  metadata,
})

It also exports dense, sparse, and hybrid model contracts plus distance helpers.

@anvia/core/vector-store exports InMemoryVectorStore, VectorStore, HybridVectorStore, retrieval/search/inspection types, vectorFilter, createVectorSearchTool, ingestVectorText, and ingestVectorDocuments.

const store = InMemoryVectorStore.fromDocuments({ documents: embedded })
const results = await retrieveDocuments({
  store,
  model: embeddingModel,
  query,
  topK: 5,
  filter,
})

For raw text, the ingestion helpers share Core's deterministic document chunking and replace the complete embedded representation for each stable source ID:

await ingestVectorText({
  store,
  document: { id: 'incident-42', text, metadata: { tenant: 'acme' } },
  embeddingModel,
  chunking: {
    strategy: 'recursive',
    maxSize: 1_000,
    overlap: 100,
    separators: ['\n\n', '\n', ' '],
  },
})

Documents

@anvia/core/documents exports chunkText, chunkTextDocuments, and their option/result types. The shared records are TextDocument, TextDocumentChunk, TextDocumentMetadata, and TextDocumentChunkingOptions.

The application owns file discovery, storage reads, document parsing or OCR, upload authorization, malware scanning, and source IDs. Pass normalized text into Core; provider-specific PDF attachments are a separate completion capability.

Structured extraction

Import from @anvia/core/extractor.

const result = await extract({
  model,
  text,
  outputSchema: schema,
  instructions: 'Extract stated facts only.',
  retries,
  temperature,
  maxTokens,
  providerOptions,
})

console.log(result.output)

The result includes schema-validated output, normalized content, cumulative usage, and rawResponse. Exhausted attempts throw ExtractionError.

Pipelines

Import from @anvia/core/pipeline.

const pipeline = new Pipeline({
  id: 'ticket-triage',
  inputSchema: ticketSchema,
  name: 'Ticket triage',
  description: 'Classifies one support ticket.',
  metadata: { owner: 'support' },
  observability: {
    observers: { telemetry: pipelineObserver },
    primaryTrace: 'telemetry',
    errorPolicy: 'ignore',
  },
})
  .step({
    id: "step-1",
    name: 'Normalize',
    run: ({ input }) => normalizeTicket(input),
  })
  .parallel({
    id: "parallel-1",
    branches: { policy: policyPipeline, signals: signalPipeline },
  })
  .step({
    id: "step-2",
    run: ({ input }) => mergeResults(input),
  })
  .agent({
    id: "agent-1",
    agent: synthesizer,
    suspension: "reject",
    request: ({ input }) => ({ prompt: String(input) }),
  })

Pipeline is immutable; each composition method returns a new typed pipeline. Public composition methods are step, compose, parallel, agent, and extract; compose({ id, pipeline }) nests another pipeline as a single stage.

const result = await pipeline.run({
  input,
  trace: { sessionId },
  observer,
  failOnObserverError: false,
})

console.log(result.trace)

await pipeline.runBatch({
  inputs,
  concurrency: 4,
})

const graph = pipeline.graph()

Constructor-level observability configures named run and stage observers. primaryTrace selects which observer contributes result.trace; errorPolicy is 'ignore' by default and can be set to 'throw'. For Agent stages, Core propagates the stage trace only when the Pipeline and Agent primaryTrace names match.

The observer passed to run() is the separate PipelineRunObserver stage-event sink. failOnObserverError applies only to that sink.

The subpath exports graph and stage metadata plus PipelineObserver, PipelineRunObservation, PipelineStageObservation, their lifecycle argument types, PipelineObservabilityOptions, PipelineTraceOptions, PipelineTraceInfo, PipelineRunObserver, run-event types, batch options, and PipelineObserverDispatchError.

Media

Use the direct helpers from their capability subpaths:

const image = await generateImage({
    prompt: prompt,
    model: imageModel,
    width: 1024,
    height: 1024,
    providerOptions,
    retries
})

const speech = await generateSpeech({
    text: text,
    model: audioModel,
    voice: 'alloy',
    speed: 1,
    providerOptions,
    retries
})

const transcript = await transcribe({
    audio: {
        data: audioBytes,
        filename: 'recording.wav'
    },
    model: transcriptionModel,
    language: 'en',
    prompt,
    temperature: 0,
    providerOptions,
    retries
})

Model, request, response, result, and retry types are exported from @anvia/core/image-generation, @anvia/core/speech-generation, and @anvia/core/transcription.

MCP and skills

@anvia/core/mcp exports only isMcpTool and the lightweight McpServer, McpTool, and McpServerInfo types used by Agent. Connection ownership, transports, discovery, result mapping, and cleanup live in the optional @anvia/mcp package.

The built-in HTTP transport has an explicit configuration boundary. McpStreamableHttpTransport is exported from @anvia/mcp, not from Core:

type McpStreamableHttpTransport = {
  type: 'streamableHttp'
  url: string | URL
  ssrfProtection?: 'strict' | 'disabled'
  headers?: Readonly<Record<string, string>>
  authProvider?: OAuthClientProvider
  reconnectionOptions?: StreamableHTTPReconnectionOptions
  sessionId?: string
}

headers applies string values only to the exact MCP endpoint. Redirects fail, OAuth traffic receives none of those headers, and transport-owned protocol headers cannot be overridden. Arbitrary requestInit is not supported. A static Authorization header and authProvider are mutually exclusive.

Streamable HTTP accepts ssrfProtection?: 'strict' | 'disabled' and defaults to 'strict'. Use the explicit opt-out only for an application-owned local or private endpoint:

import { McpClient } from '@anvia/mcp'

const localMcp = new McpClient({
  name: 'local',
  transport: {
    type: 'streamableHttp',
    url: 'http://localhost:3000/mcp',
    ssrfProtection: 'disabled',
  },
})

See MCP transport configuration for header scoping and SSRF guidance.

@anvia/core/skills exports skill.local(...), loadSkills(...), SkillSet, and validation types.

Redaction

@anvia/core/redaction exports the shared PII-redaction implementation used by the Lens and Langfuse adapters:

import { createRedactor, DEFAULT_PATTERNS } from '@anvia/core/redaction'

const redactor = createRedactor({ replacement: '<redacted>' })
const safeValue = redactor.redact(value)

The subpath also exports Redactor, RedactionOptions, and RedactionPattern. A redactor returns non-mutating copies and provides redactString(), redactObject(), redactMessages(), and patternNames(). Custom patterns replace the defaults rather than extending them. Default patterns cover email addresses, validated payment cards, IPv4 addresses, standalone phone-number runs, JWTs, common API-key prefixes, and bearer tokens. Traversal marks circular references and values deeper than 16 levels instead of exporting them unchanged.

Observability

@anvia/core/observability exports the observer contracts for runs, model generations, and tools, along with trace options and AgentObserverDispatchError. Observer implementations come from integrations such as @anvia/lens, @anvia/langfuse, and @anvia/otel.

Attach observers to the agent and supply request identity through the run's trace option:

const result = await agent.generate({
    prompt: input,
    trace: {
        name: 'support-reply',
        userId,
        sessionId,
        tags: ['support'],
        metadata: { channel: 'web' },
    }
})

Evaluations

@anvia/core/evals exports defineEvalSuite, defineMetric, runEvalSuite, built-in metrics, judge helpers, reporters, result formatters, and evaluation case/run types.

Use the production evaluations guide for suite construction and reporter lifecycle. Use the package source for an exhaustive symbol list tied to the installed version.

Evaluation assertions and interaction targets

Import these APIs from @anvia/core/evals:

API	Contract
defineEvalCases(cases)	Preserve literal case IDs and input/expected types.
defineEvalExpectations(suite, expectations)	Type-check case and metric names.
assertEvalTotals(result, expected)	Check specified metric/case counts.
assertEvalOutcomes(result, expected)	Check per-case metrics; unspecified required metrics default to pass.
EvalAssertionError	Assertion failure with mismatches: string[].
evalExitCode(result, expectations?)	Compute 0, 1, or 2 without changing process state.
runEvalCli(options)	Run, print, and optionally raise the process exit code.
formatEvalResult(result, options?) / printEvalResult(result, options?)	Format or write pretty/JSON/quiet output with optional truncation and redaction.
agentEvalTarget({ agent, request, interactions?, output? })	Map inputs, resume with a bounded responder, select completed output.
AgentEvalSuspensionError	Missing responder or exhausted response limit; inspect result.

See expectations and the offline interaction example.

Message and interaction boundary validation

@anvia/core and @anvia/core/completion export createMessageSchema({ metadataSchema }), isMessage(value), parseMessage(value), parseMessages(value), messageSchema, and messagesSchema. A custom metadata schema still permits absent metadata; isMessage checks the standard contract only. See metadata validation.

@anvia/core/agent/interactions exports agentContinuationSchema, agentInteractionRequestSchema, agentInteractionResponseSchema, parseAgentContinuation, parseAgentInteractionRequest, parseAgentInteractionResponse, and assertAgentInteractionResponse(request, response), plus the continuation/request/response and question types. Parsing checks shape; the assertion matches answers to the request. See the server boundary example.

Custom completion controls and context accounting

API	Public import path	Contract
defineCompletionModelControls(controls)	root or completion	Validate/freeze typed select controls.
REASONING_EFFORT_CONTROL_ID	root or completion	Standard control ID reasoningEffort.
mergeCompletionControlValues(defaults, overrides)	completion	Merge string values; overrides win, no option validation.
assertCompletionControlsSupported(model, values)	completion	Reject unknown IDs/unsupported options.
assertCompletionRequestSupported(model, request, options?)	completion	Check request controls and capabilities, including optional streaming.
resolveModelContextLimits(modelId, catalog, override?)	root or completion	Override, exact catalog entry, or undefined.
calculateContextUsage(usage, modelInfo)	root or completion	Input-token context-window snapshot, or undefined.
withContextUsage(response, modelInfo)	root or completion	Attach usable context accounting to a response.

Here root means @anvia/core; completion means @anvia/core/completion. Types include CompletionModelControls, CompletionModelSelectControl, CompletionControlValues, CompletionModelControlsOf, ModelContextLimits, CompletionModelInfo, and ContextUsage. See the complete custom model.

Provider and adapter error reference

Public class	Import path	Trigger and diagnostic fields
CompletionProviderOutputError	root or completion	Invalid/incomplete provider contract; code, kind, optional toolCallId, finishReason, usage; no raw arguments.
AgentRunBlockedError	root or agent	Completed-output adapter received blocked outcome; result.
AgentToolSuspensionError	root or agent	Agent-as-tool received an interaction; result.
AgentStreamClosedError	root or agent	Steering after input closed.
PipelineAgentSuspensionError	pipeline	Agent stage received an interaction; result.
AgentEvalSuspensionError	evals	Missing/exhausted eval responder; result.
ToolNotFoundError, ToolJsonError, ToolCallError	tool	Registry/JSON/execution failure; toolName or cause.
ToolResultSerializationError	tool	Unsupported normalized result; raw output.

Paths above mean @anvia/core and @anvia/core/{completion,agent,pipeline,evals,tool} respectively. COMPLETION_PROVIDER_OUTPUT_ERROR_CODE is exported with the provider error. Full outcomes, raw outputs, and causes need application redaction. See provider kinds and retry policy, adapter behavior, and tool normalization.

Memory scope keys

createMemoryScopeKey({ scope, includeUserId?, metadataKeys? }): string is exported from @anvia/core and @anvia/core/memory. CreateMemoryScopeKeyOptions, MemoryScopeKeyOptions, and MemoryScopeKeyResolver are exported from the memory subpath. The helper derives an ordered JSON key; it does not authorize a scope or enforce required tenant metadata. See the complete custom-store factory for applying the same policy to canonical data, errors, inspection, and compaction.

Integration utility reference

These exported utilities support adapter, reporter, and presentation code. Import them from the specified public subpath; a discriminator or formatter is not a complete validation boundary.

Subpath after @anvia/core/	Utilities and behavior
completion	normalizeDocuments(documents) returns a user message or undefined for an empty list; formatDocument(document) renders text with file/metadata markers, not an escaped security envelope.
completion	reasoningDisplayText(reasoningOrDetails) joins visible text/summary details; textFromAssistantContent(parts) joins text parts. Neither decrypts reasoning or redacts content.
completion	isStreamingCompletionModel(model) checks for a streaming method; isProviderTool(value) checks the provider-tool shape and JSON-safe configuration.
agent	isVectorContext(value) checks the context marker, store search method, and model presence; it does not probe the store or model.
tool	isQuestionTool(tool) checks the question-tool marker; parseToolArgs(rawJson) parses strict JSON but does not apply a tool's input schema.
tool	normalizeToolResultOutput(value) returns normalized text/JSON/content or throws ToolResultSerializationError; toolResultContentToText(parts) renders text and file media-type placeholders.
evals	selectPromptOutput(args) requires an output object with a string output field.
evals	resolveEvalTraceRef({ output?, input?, metadata? }) selects a trace from output, input, then metadata; defaultEvalTraceSelector(args) applies that order to a case.
evals	projectEvalOutcome(outcome, dataType, projectScore?) maps outcomes/scores into reporter projections, with optional numeric/categorical fields and explanation.
evals	EvalTimeoutError.timeoutMs identifies case timeout; suite cancellation rejects with its abort reason (EvalAbortError when no reason is available). EvalFailFastError has caseId/outcome; EvalReporterDispatchError has phase/aggregate errors.
redaction	passesLuhn(digits) checks a digit-string checksum only; it does not establish a valid card, issuer, ownership, or permission.

Low-level runInputGuardrails, runOutputGuardrails, normalizeGuardrailPolicies, appendGuardrailPolicies, and hasEnforcedOutputGuardrails are exported from @anvia/core/guardrails for runtime integrators. Ordinary applications use policies attached to Agents; separate tutorials for these runtime helpers are intentionally excluded from the coverage inventory.

Embedding distances

Import these numerical functions from @anvia/core/embeddings:

Function	Result
dotProduct(left, right)	Sum of pairwise products.
cosineSimilarity(left, right)	Normalized dot product; returns zero if either magnitude is zero.
angularDistance(left, right)	acos(clampedCosine) / PI.
euclideanDistance(left, right)	Square root of summed squared differences.
manhattanDistance(left, right)	Sum of absolute differences.
chebyshevDistance(left, right)	Maximum absolute difference; zero for empty vectors.

Dimensions must match. These functions do not validate finite elements or normalize a store's score semantics; use vectors from a compatible embedding model.

import { cosineSimilarity, euclideanDistance } from '@anvia/core/embeddings'

const similarity = cosineSimilarity([1, 0], [1, 0])
const distance = euclideanDistance([0, 0], [3, 4])
console.log(similarity, distance) // 1, 5

See the contributor SDK coverage review for the entrypoint map, tested feature inventory, explicit exclusions, and validation scope.