AI Agent

An agent is an AI-powered participant in your PURISTA system. Unlike a command (deterministic code) or a subscription (fire-and-forget handler), an agent uses a language model to reason about inputs, choose tools, and produce structured outputs.

Agent support is part of @purista/core via ServiceBuilder.getAgentQueueBuilder(...). Concrete model backends come from provider packages such as @purista/harness-openai.

In this section

Quick reference

Agent lifecycle

flowchart LR
    A[Input Received] --> B[Input Validation]
    B --> C[Before Guards]
    C --> D[Invoke Agent]
    D --> E[Model Reasoning]
    E --> F[Tool Calls]
    F --> G[Structured Output]
    G --> H[Return Result]
    E -.->|Streaming| I[writer.write chunk]
    I --> J[writer.close final]

Key principles

• Agents generate a queue, worker, command, and stream that use AI models for reasoning.
• Agent builders are available from @purista/core.
• Use getAgentQueueBuilder(agentName, description) to define an agent.
• Schema methods: addPayloadSchema, addParameterSchema, addOutputSchema.
• Set the agent logic with setRunFunction(async context => { ... }).
• Model capabilities gate which methods are available on context.harness.models.
• Tools: canInvoke for command tools, canInvokeAgent for child agents.
• Skills: useSkills(names), useBuiltInTools(names|false).
• Session: setSessionPolicy({ mode: 'ephemeral'|'conversation', payloadPath? }).
• Runtime requires queueBridge and ai.models in service instance options.
• HTTP exposure: exposeAsHttpEndpoint(method, path, options) registers either a JSON response endpoint or an SSE stream endpoint.
• canEmit and canConsumeStream are not implemented on AgentQueueBuilder.
• Context: context.invoke.tools['serviceName.version.command'].call(payload, parameter?).
• Context: context.invoke.agents['agentName.version'].run(payload, parameter?).