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.

Agents require the @purista/ai-harness package. Install it alongside @purista/core to get getAgentBuilder on ServiceBuilder and the AI harness infrastructure.

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 are commands/streams that use AI models for reasoning.
• Agents require @purista/ai-harness in addition to @purista/core.
• Use getAgentBuilder(agentName, description) to define an agent.
• Schema methods: addPayloadSchema, addParameterSchema, addOutputSchema.
• Set the agent logic with setAgentFunction(async (ctx, payload) => { ... }).
• 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.
• 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?).