ACAgentic Craft

Foundation~12 minHazelJS

Augmented LLM

A single HazelJS AgentRuntime call enriched with retrieval, bounded tools, or structured output—without an open-ended agent loop.

Authors
editorial-team
Published
Last reviewed

Problem

You need better answers than a raw prompt provides, but a multi-step autonomous agent would add unjustified operational complexity.

Context

Product features that classify, extract, draft, or answer with grounding inside a HazelJS DI/HTTP app. Common first step before introducing full AgentRuntime tool loops.

Forces and constraints

  • Quality improves with retrieval, tools, or schema constraints
  • Latency and cost must stay predictable
  • Operators need a simple failure model
  • Side effects should remain rare or user-triggered

Recommended design

Host one (or a fixed small number of) model steps inside @hazeljs/agent: retrieve via memory/RAG peers, optionally expose a tight ToolRegistry allow-list, call AgentRuntime.execute with maxSteps capped low (often 1–2), validate structured output with contracts/guardrails, return. Control flow stays in application code—not an open decide/act loop with durableSuspend.

Minimal pseudocode

import { AgentRuntime, ToolRegistry } from '@hazeljs/agent';

const runtime = new AgentRuntime({
  toolRegistry: new ToolRegistry(/* read-only tools only */),
  // no durableSuspend — single-shot path
});

const result = await runtime.execute('AugmentedAnswerer', { query }, {
  maxSteps: 2,           // bound tool round-trips
  enableRAG: true,
  enableMemory: false,
  contract: answerSchema, // optional structured-output gate
});

return result.output;

Failure modes

  • Retriever returns irrelevant or poisoned documents
  • Schema/contract validation fails silently and UI shows empty success
  • Hidden high maxSteps turns this into an unmanaged tool-using agent
  • Over-long RAG context degrades answer quality

Security considerations

  • Treat retrieved text and tool outputs as untrusted; pair with @hazeljs/guardrails
  • Do not put secrets in prompts or DNA overlays
  • Scope ToolRegistry credentials tightly even for single-shot calls

Observability signals

  • Emit model/RAG spans via @hazeljs/observability
  • Inspect the short timeline with Inspector getTimeline({ executionId })
  • Log retrieval hit counts and token/cost attributes per execute()

Evaluation approach

Offline golden questions with citation/grounding checks; contract validity rate; latency SLO adherence against AgentRuntime.execute.

Trade-offs

  • Simpler ops than durable agents, less coverage of open-ended tasks
  • Fixed flow is auditable but rigid when branching explodes

Sources

Related patterns