# AgentQueueBuilder API

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

---
Canonical: /handbook/api/classes/_purista_core.AgentQueueBuilder/
Source: AgentQueueBuilder/AgentQueueBuilder.ts
Format: Markdown for agents
---

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

Package: `@purista/core`

## Signature

```typescript
class AgentQueueBuilder<S>
```

## Examples

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

## Members

### Constructors

- `new constructor<S>(serviceName: string, serviceVersion: string, agentName: string, description: string)`

### Methods

- `addModel<Alias, Binding>(alias: Alias, binding: Binding): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"] & Record<Alias, Binding>, S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"]>>` — Declare a model alias that must be bound when the owning service is instantiated.
- `addOutputSchema<OutputSchema>(schema: OutputSchema): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], OutputSchema, S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"]>>` — Add the final output schema returned by the agent command or aggregate stream response.
- `addParameterSchema<ParameterSchema>(schema: ParameterSchema): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], ParameterSchema, S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"]>>` — Add the parameter schema used by the generated queue, command, stream, and agent handler.
- `addPayloadSchema<PayloadSchema>(schema: PayloadSchema): AgentQueueBuilder<AgentQueueBuilderTypes<PayloadSchema, S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"]>>` — Add the payload schema used by the generated queue, command, stream, and agent handler.
- `canInvoke<Output, Payload, Parameter, ServiceName, Version, CommandName>(serviceName: ServiceName, serviceVersion: Version, commandName: CommandName, schemas?: { outputSchema: Output; parameterSchema: Parameter; payloadSchema: Payload }): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"] & Record<`template`, AllowedCommandToolDefinition<unknown, unknown, unknown>>, S["AgentTools"], S["Execution"], S["Metrics"]>>` — Allow the agent handler to call a PURISTA command through `context.invoke.tools`.
- `canInvokeAgent<Output, Payload, Parameter, AgentName, Version>(agentName: AgentName, serviceVersion: Version, schemas?: { outputSchema: Output; parameterSchema: Parameter; payloadSchema: Payload }): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"] & Record<`template`, AllowedAgentDefinition<unknown, unknown, unknown>>, S["Execution"], S["Metrics"]>>` — Allow this agent to call another attached agent through `context.invoke.agents`.
- `defineMetric<MetricName, Definition>(_name: MetricName, _definition: Definition): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], S["Execution"], S["Metrics"] & mapped>>` — Declare a custom application metric available only in this agent handler.
- `exposeAsHttpEndpoint(method: SupportedHttpMethod, path: string, options?: Omit<AgentHttpExposure, "method" | "path">): AgentQueueBuilder<S>` — Expose the generated agent command or stream as an HTTP endpoint.
- `getDefinition(): Promise<AttachedAgentDefinition<S>>` — Generate the attached agent and its queue, worker, command, and stream definitions.
- `getManifest(): AgentManifest<S["Models"]>` — Return the provider-neutral manifest for this agent without generating core definitions.
- `makeEndpointPublic(): AgentQueueBuilder<S>` — Mark the generated HTTP endpoint public in OpenAPI/security metadata.
- `setExecutionPolicy(policy: AgentExecutionPolicy): AgentQueueBuilder<S>` — Merge queue worker execution policy for the generated agent worker and queue.
- `setExecutionProfile(profile: "longRunning", options: { maxRuntimeMs: number; strict: boolean }): AgentQueueBuilder<S>` — Apply a core queue execution profile to the generated agent queue.
- `setHarnessAgent(this: AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], undefined, S["Metrics"]>>, definition: AgentDefinition<any>): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], "harnessAgent", S["Metrics"]>>` — Use a provider-neutral `@purista/harness` agent definition as this agent's execution.
- `setHarnessWorkflow(this: AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], undefined, S["Metrics"]>>, definition: WorkflowDefinition<any>): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], "harnessWorkflow", S["Metrics"]>>` — Use a provider-neutral `@purista/harness` workflow definition as this agent's execution.
- `setResponseMode(mode: AgentResponseMode, options?: AgentResponseModeOptions): AgentQueueBuilder<S>` — Configure how a queued agent run exposes its final result contract.
- `setRunFunction(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"]>): AgentQueueBuilder<AgentQueueBuilderTypes<S["PayloadSchema"], S["ParameterSchema"], S["OutputSchema"], S["Resources"], S["Models"], S["CommandTools"], S["AgentTools"], "runFunction", S["Metrics"]>>` — Use a plain async run function as this agent's execution.
- `setSandboxPolicy(policy: AgentSandboxPolicy): AgentQueueBuilder<S>` — Attach sandbox configuration consumed by compatible agent runtimes.
- `setSessionPolicy(policy: AgentSessionPolicy): AgentQueueBuilder<S>` — Configure harness session behavior for this attached agent.
- `setStreamingMode(mode: "stream" | "aggregate"): AgentQueueBuilder<S>` — Choose whether the generated HTTP projection streams chunks or returns an aggregate response.
- `setSuccessEventName(eventName: string): AgentQueueBuilder<S>` — Set the success event name used by generated command and result policies.
- `useBuiltInTools(namesOrFalse: false | typeOperator): AgentQueueBuilder<S>` — Restrict or disable harness built-in tools for this agent.
- `useSkills(names: typeOperator, resourceName?: string): AgentQueueBuilder<S>` — Declare named skill references the runtime can load for this agent.