PURISTA

Appearance

PURISTA API

PURISTA API / @purista/core / AgentQueueBuilder

Class: AgentQueueBuilder<S> ​

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:81

Builds an attached PURISTA agent from normal core queue, worker, command, stream definitions, and a provider-neutral agent manifest.

Example ​

ts
const triage = service
  .getAgentQueueBuilder('supportTriage', 'Classifies tickets')
  .addModel('primary', { model: 'gpt-4.1-mini', capabilities: ['object'] })
  .setRunFunction(async context => ({ priority: 'high' }))

Type Parameters ​

S ​

S extends AnyAgentQueueBuilderTypes = AgentQueueBuilderTypes

Constructors ​

Constructor ​

new AgentQueueBuilder<S>(serviceName, serviceVersion, agentName, description): AgentQueueBuilder<S>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:100

Parameters ​

serviceName ​

string

serviceVersion ​

string

agentName ​

string

description ​

string

Returns ​

AgentQueueBuilder<S>

Methods ​

addModel() ​

addModel<Alias, Binding>(alias, binding): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"] & Record<Alias, Binding>, S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"]>>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:189

Type Parameters ​

Alias ​

Alias extends string

Binding ​

Binding extends AgentModelBinding

Parameters ​

alias ​

Alias

binding ​

Binding

Returns ​

AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"] & Record<Alias, Binding>, S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"]>>

addOutputSchema() ​

addOutputSchema<OutputSchema>(schema): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], OutputSchema, S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"]>>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:172

Type Parameters ​

OutputSchema ​

OutputSchema extends Schema

Parameters ​

schema ​

OutputSchema

Returns ​

AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], OutputSchema, S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"]>>

addParameterSchema() ​

addParameterSchema<ParameterSchema>(schema): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], ParameterSchema, S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"]>>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:155

Type Parameters ​

ParameterSchema ​

ParameterSchema extends Schema

Parameters ​

schema ​

ParameterSchema

Returns ​

AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], ParameterSchema, S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"]>>

addPayloadSchema() ​

addPayloadSchema<PayloadSchema>(schema): AgentQueueBuilder<AgentQueueBuilderTypes<PayloadSchema, S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"]>>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:138

Type Parameters ​

PayloadSchema ​

PayloadSchema extends Schema

Parameters ​

schema ​

PayloadSchema

Returns ​

AgentQueueBuilder<AgentQueueBuilderTypes<PayloadSchema, S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"]>>

canInvoke() ​

canInvoke<Output, Payload, Parameter, ServiceName, Version, CommandName>(serviceName, serviceVersion, commandName, schemas?): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"] & Record<`${ServiceName}.${Version}.${CommandName}`, AllowedCommandToolDefinition<Output, Payload, Parameter>>, S["AgentTools"], S["Execution"], S["Metrics"]>>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:217

Type Parameters ​

Output ​

Output extends Schema

Payload ​

Payload extends Schema

Parameter ​

Parameter extends Schema

ServiceName ​

ServiceName extends string

Version ​

Version extends string

CommandName ​

CommandName extends string

Parameters ​

serviceName ​

ServiceName

serviceVersion ​

Version

commandName ​

CommandName

schemas? ​
outputSchema? ​

Output

parameterSchema? ​

Parameter

payloadSchema? ​

Payload

Returns ​

AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"] & Record<`${ServiceName}.${Version}.${CommandName}`, AllowedCommandToolDefinition<Output, Payload, Parameter>>, S["AgentTools"], S["Execution"], S["Metrics"]>>

canInvokeAgent() ​

canInvokeAgent<Output, Payload, Parameter, AgentName, Version>(agentName, serviceVersion, schemas?): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"] & Record<`${AgentName}.${Version}`, AllowedAgentDefinition<Output, Payload, Parameter>>, S["Execution"], S["Metrics"]>>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:254

Type Parameters ​

Output ​

Output extends Schema

Payload ​

Payload extends Schema

Parameter ​

Parameter extends Schema

AgentName ​

AgentName extends string

Version ​

Version extends string

Parameters ​

agentName ​

AgentName

serviceVersion ​

Version

schemas? ​
outputSchema? ​

Output

parameterSchema? ​

Parameter

payloadSchema? ​

Payload

Returns ​

AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"] & Record<`${AgentName}.${Version}`, AllowedAgentDefinition<Output, Payload, Parameter>>, S["Execution"], S["Metrics"]>>

defineMetric() ​

defineMetric<MetricName, Definition>(_name, _definition): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"] & { [K in string]: Definition }>>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:119

Declare a custom application metric available only in this agent handler.

Type Parameters ​

MetricName ​

MetricName extends string

Definition ​

Definition extends PuristaMetricDefinition<any>

Parameters ​

_name ​

MetricName

_definition ​

Definition

Returns ​

AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"] & { [K in string]: Definition }>>

Example ​

ts
agent.defineMetric('app.agent.escalations', {
  kind: 'counter',
  unit: '{escalation}',
  description: 'Escalated agent runs',
})

exposeAsHttpEndpoint() ​

exposeAsHttpEndpoint(method, path, options?): AgentQueueBuilder<S>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:452

Parameters ​

method ​

SupportedHttpMethod

path ​

string

options? ​

Omit<AgentHttpExposure, "method" | "path">

Returns ​

AgentQueueBuilder<S>

getDefinition() ​

getDefinition(): Promise<AttachedAgentDefinition<S>>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:487

Returns ​

Promise<AttachedAgentDefinition<S>>

getManifest() ​

getManifest(): AgentManifest<S["Models"]>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:483

Returns ​

AgentManifest<S["Models"]>

makeEndpointPublic() ​

makeEndpointPublic(): AgentQueueBuilder<S>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:469

Returns ​

AgentQueueBuilder<S>

setExecutionPolicy() ​

setExecutionPolicy(policy): AgentQueueBuilder<S>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:395

Parameters ​

policy ​

AgentExecutionPolicy

Returns ​

AgentQueueBuilder<S>

setExecutionProfile() ​

setExecutionProfile(profile, options): AgentQueueBuilder<S>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:410

Apply a core queue execution profile to the generated agent queue.

Parameters ​

profile ​

"longRunning"

options ​
maxRuntimeMs ​

number

strict? ​

boolean

Returns ​

AgentQueueBuilder<S>

Example ​

ts
agent.setExecutionProfile('longRunning', {
  maxRuntimeMs: 30 * 60_000,
})

setHarnessAgent() ​

setHarnessAgent(this, definition): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], "harnessAgent", S["Metrics"]>>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:287

Parameters ​

this ​

AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], undefined, S["Metrics"]>>

definition ​

AgentDefinition<any>

Returns ​

AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], "harnessAgent", S["Metrics"]>>

setHarnessWorkflow() ​

setHarnessWorkflow(this, definition): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], "harnessWorkflow", S["Metrics"]>>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:320

Parameters ​

this ​

AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], undefined, S["Metrics"]>>

definition ​

WorkflowDefinition<any>

Returns ​

AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], "harnessWorkflow", S["Metrics"]>>

setResponseMode() ​

setResponseMode(mode, options?): AgentQueueBuilder<S>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:437

Configure how a queued agent run exposes its final result contract.

Long-running response modes enqueue the agent queue and keep jobId and agent runId as separate metadata in the generated definitions.

Parameters ​

mode ​

AgentResponseMode

options? ​

AgentResponseModeOptions

Returns ​

AgentQueueBuilder<S>

Example ​

ts
agent.setResponseMode('accepted', {
  resultPolicy: 'state-and-event',
})

setRunFunction() ​

setRunFunction(this, handler): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], "runFunction", S["Metrics"]>>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:353

Parameters ​

this ​

AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], undefined, S["Metrics"]>>

handler ​

AgentHandler<InferIn<S["PayloadSchema"]>, InferIn<S["ParameterSchema"]>, S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], Infer<S["OutputSchema"]>, S["Metrics"]>

Returns ​

AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], "runFunction", S["Metrics"]>>

setSandboxPolicy() ​

setSandboxPolicy(policy): AgentQueueBuilder<S>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:447

Parameters ​

policy ​

AgentSandboxPolicy

Returns ​

AgentQueueBuilder<S>

setSessionPolicy() ​

setSessionPolicy(policy): AgentQueueBuilder<S>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:442

Parameters ​

policy ​

AgentSessionPolicy

Returns ​

AgentQueueBuilder<S>

setStreamingMode() ​

setStreamingMode(mode): AgentQueueBuilder<S>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:464

Parameters ​

mode ​

"stream" | "aggregate"

Returns ​

AgentQueueBuilder<S>

setSuccessEventName() ​

setSuccessEventName(eventName): AgentQueueBuilder<S>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:477

Parameters ​

eventName ​

string

Returns ​

AgentQueueBuilder<S>

useBuiltInTools() ​

useBuiltInTools(namesOrFalse): AgentQueueBuilder<S>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:212

Parameters ​

namesOrFalse ​

false | readonly BuiltinToolName[]

Returns ​

AgentQueueBuilder<S>

useSkills() ​

useSkills(names, resourceName?): AgentQueueBuilder<S>

Defined in: AgentQueueBuilder/AgentQueueBuilder.ts:207

Parameters ​

names ​

readonly string[]

resourceName? ​

string

Returns ​

AgentQueueBuilder<S>