# Agent AI-powered service participants that use language models, tools, and skills to reason and act. --- Canonical: /handbook/blocks/agent-pattern/ Source: web/src/content/handbook-cards/blocks/agent-pattern.mdx Format: Markdown for agents --- 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`.

AI on normal PURISTA rails

Agents reuse the same service, queue, command, stream, event bridge, and HTTP infrastructure as the rest of PURISTA. They are not a separate application lane.

## In this section

What is an Agent?

Understand agent types, model capabilities, session policies, and runtime requirements.

The Agent Builder

Define typed agents with models, tools, skills, execution policies, and streaming modes.

Agent Workflows

Chain agents, orchestrate multi-step reasoning, and manage state across agent boundaries.

HTTP Exposure

Expose agents as REST endpoints with aggregate or accepted response contracts.

Testing

Test agents with harnesses, scripted models, and deterministic tool responses.

## Quick reference ### Agent lifecycle ```mermaid 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?)`.