PURISTA API

---

PURISTA API / @purista/ai / AgentBuilder

Class: AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:295

Type Parameters

KnowledgeAliases

KnowledgeAliases extends string = never

ModelAliases

ModelAliases extends string = never

TextAliases

TextAliases extends string = never

StreamAliases

StreamAliases extends string = never

EmbeddingAliases

EmbeddingAliases extends string = never

RerankAliases

RerankAliases extends string = never

ObjectAliases

ObjectAliases extends string = never

AgentInvokes

AgentInvokes extends AgentInvokeList = AgentInvokeList

Constructors

Constructor

new AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>(info): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:328

Parameters

info

AgentInfo

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Methods

addContextSchema()

addContextSchema(schema): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:676

Parameters

schema

Schema

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

addOutputSchema()

addOutputSchema(schema): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:669

Parameters

schema

Schema

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

addParameterSchema()

addParameterSchema(schema): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:661

Parameters

schema

Schema

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

addPayloadSchema()

addPayloadSchema(schema): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:649

Parameters

schema

Schema

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

build()

build(): AgentDefinition<KnowledgeAliases>

Defined in: packages/ai/src/builder/AgentBuilder.ts:1453

Returns

AgentDefinition<KnowledgeAliases>

---

canEmit()

canEmit<EventName, T>(eventName, schema): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:625

Type Parameters

EventName

EventName extends string

T

T extends Schema

Parameters

eventName

EventName

schema

T

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

canInvoke()

canInvoke(serviceName, serviceVersion, commandName, outputSchema?, payloadSchema?, parameterSchema?): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:518

Parameters

serviceName

string

serviceVersion

string

commandName

string

outputSchema?

Schema

payloadSchema?

Schema

parameterSchema?

Schema

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

canInvokeAgent()

canInvokeAgent<Payload, Parameter, SName, Version>(agentName, agentVersion, invokeConfigOrParameterSchema?): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes & Record<SName, Record<Version, { call: (payload, parameter?) => AgentInvocation<{ history: any[]; message: any; }>; }>>>

Defined in: packages/ai/src/builder/AgentBuilder.ts:555

Type Parameters

Payload

Payload extends Schema = ZodObject<{ attachments: ZodDefault<ZodOptional<ZodArray<ZodAny>>>; conversationId: ZodOptional<ZodString>; history: ZodDefault<ZodOptional<ZodArray<ZodAny>>>; message: ZodString; }, $loose>

Parameter

Parameter extends Schema = Schema

SName

SName extends string = string

Version

Version extends string = string

Parameters

agentName

SName

agentVersion

Version

invokeConfigOrParameterSchema?

Parameter | AgentInvokeConfig<Payload, Parameter>

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes & Record<SName, Record<Version, { call: (payload, parameter?) => AgentInvocation<{ history: any[]; message: any; }>; }>>>

---

defineModel()

defineModel<Alias, Caps>(alias, options?): AgentBuilder<KnowledgeAliases, ModelAliases | Alias, TextAliases | ResolveCapability<Caps, "text"> extends true ? Alias : never, StreamAliases | ResolveCapability<Caps, "stream"> extends true ? Alias : never, EmbeddingAliases | ResolveCapability<Caps, "embedding"> extends true ? Alias : never, RerankAliases | ResolveCapability<Caps, "rerank"> extends true ? Alias : never, ObjectAliases | ResolveCapability<Caps, "json"> extends true ? Alias : never>

Defined in: packages/ai/src/builder/AgentBuilder.ts:372

Type Parameters

Alias

Alias extends string

Caps

Caps extends readonly AgentModelCapability[] | undefined = undefined

Parameters

alias

Alias

options?

capabilities?

Caps

Returns

AgentBuilder<KnowledgeAliases, ModelAliases | Alias, TextAliases | ResolveCapability<Caps, "text"> extends true ? Alias : never, StreamAliases | ResolveCapability<Caps, "stream"> extends true ? Alias : never, EmbeddingAliases | ResolveCapability<Caps, "embedding"> extends true ? Alias : never, RerankAliases | ResolveCapability<Caps, "rerank"> extends true ? Alias : never, ObjectAliases | ResolveCapability<Caps, "json"> extends true ? Alias : never>

---

exposeAsHttpEndpoint()

exposeAsHttpEndpoint(method, path, contentTypeRequest?, contentEncodingRequest?, contentTypeResponse?, contentEncodingResponse?): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:714

Parameters

method

string

path

string

contentTypeRequest?

string

contentEncodingRequest?

string

contentTypeResponse?

string

contentEncodingResponse?

string

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

makeEndpointPublic()

makeEndpointPublic(): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:766

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

persistConversation()

Call Signature

persistConversation(config): this

Defined in: packages/ai/src/builder/AgentBuilder.ts:479

Configure conversation persistence.

You can either pass a full config object or use presets:

• persistConversation('user') defaults to full strategy with a larger frame budget
• persistConversation('agent') defaults to summary strategy with a smaller frame budget

Parameters

config

AgentSessionConfig

Returns

this

Example

new AgentBuilder({ agentName: 'supportAgent', agentVersion: '1' })
  .persistConversation('user')

Call Signature

persistConversation(preset, overrides?): this

Defined in: packages/ai/src/builder/AgentBuilder.ts:480

Configure conversation persistence.

You can either pass a full config object or use presets:

• persistConversation('user') defaults to full strategy with a larger frame budget
• persistConversation('agent') defaults to summary strategy with a smaller frame budget

Parameters

preset

AgentHistoryPreset

overrides?

Partial<AgentSessionConfig>

Returns

this

Example

new AgentBuilder({ agentName: 'supportAgent', agentVersion: '1' })
  .persistConversation('user')

---

prepareCall()

prepareCall(hook): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:699

Registers a per-model-call hook that can inject metadata and AI SDK call options dynamically.

Parameters

hook

AgentPrepareCallHook

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

prepareStep()

prepareStep(hook): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:709

Registers a step-aware hook invoked for each model call.

Use this when call options need to change across iterative refinement passes.

Parameters

hook

AgentPrepareCallHook

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setCallOptionsSchema()

setCallOptionsSchema(schema): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:691

Sets a validation schema for model call options returned by prepareCall / prepareStep.

The schema is validated for every hook result before metadata is merged into model requests.

Parameters

schema

ZodType<AgentModelCallOptions>

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setContextSchema()

setContextSchema(schema): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:682

Parameters

schema

Schema

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setDescription()

setDescription(description): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:354

Parameters

description

string

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setEvaluation()

setEvaluation(profile): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:641

Parameters

profile

Record<string, unknown>

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setHandler()

setHandler<Payload, Parameter, Resources, Models>(fn): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:774

Type Parameters

Payload

Payload = unknown

Parameter

Parameter = unknown

Resources

Resources extends Record<string, unknown> = Record<string, unknown>

Models

Models extends Record<string, ModelProvider> = DeclaredModelMap<ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases>

Parameters

fn

AgentHandler<Payload, Parameter, Resources, Models, KnowledgeAliases, AgentInvokes>

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setInputSchema()

setInputSchema(schema): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:657

Parameters

schema

Schema

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setKnowledge()

setKnowledge(adapters): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:513

Parameters

adapters

KnowledgeAdapterConfig[] | undefined

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setMemory()

setMemory(config): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:509

Parameters

config

AgentSessionConfig | undefined

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setModelResource()

setModelResource(resource): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:499

Parameters

resource

{ resourceName: string; variant?: string; } | undefined

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setRetryPolicy()

setRetryPolicy(policy): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:504

Parameters

policy

RetryPolicy

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setRuntime()

setRuntime(mode): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:491

Parameters

mode

string

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setSseProtocol()

setSseProtocol(protocol): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:757

Selects the SSE wire protocol for exposed stream endpoints.

Defaults to purista when not set. This setting is only relevant when streamingMode is stream.

Parameters

protocol

AgentSseProtocol

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setStreamingMode()

setStreamingMode(mode): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:742

Parameters

mode

"stream" | "aggregate"

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setSuccessEventName()

setSuccessEventName(eventName): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:631

Parameters

eventName

string

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

setTelemetry()

setTelemetry(config): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:636

Parameters

config

{ attributes?: Record<string, string | number | boolean>; } | undefined

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

useConversationStore()

useConversationStore(config): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:417

Parameters

config

AgentSessionConfig

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

useEventBridge()

useEventBridge(name): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:359

Parameters

name

string

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

---

useKnowledgeAdapter()

Call Signature

useKnowledgeAdapter<Alias>(adapterName, options?): AgentBuilder<KnowledgeAliases | Alias, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases>

Defined in: packages/ai/src/builder/AgentBuilder.ts:422

Type Parameters

Alias

Alias extends string

Parameters

adapterName

Alias

options?

Record<string, unknown>

Returns

AgentBuilder<KnowledgeAliases | Alias, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases>

Call Signature

useKnowledgeAdapter<Adapter>(adapter): AgentBuilder<KnowledgeAliases | Adapter["adapterName"], ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases>

Defined in: packages/ai/src/builder/AgentBuilder.ts:434

Type Parameters

Adapter

Adapter extends object

Parameters

adapter

Adapter

Returns

AgentBuilder<KnowledgeAliases | Adapter["adapterName"], ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases>

---

useResource()

useResource(alias, resource): AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>

Defined in: packages/ai/src/builder/AgentBuilder.ts:364

Parameters

alias

string

resource

resourceName

string

Returns

AgentBuilder<KnowledgeAliases, ModelAliases, TextAliases, StreamAliases, EmbeddingAliases, RerankAliases, ObjectAliases, AgentInvokes>