ACAgentic Craft

Intermediate~28 minHazelJS

Assembling Agent Context

How AgentRuntime builds model-visible context each step—and how to keep it intentional with flags and observation hygiene.

Authors
editorial-team
Published
Last reviewed
Progress is stored locally in this browser.

Direct answer

Each AgentRuntime step assembles what the model sees from the goal, prior turns, tool observations, and optional memory/RAG. You control that assembly with execute/@Agent flags (enableMemory, enableRAG, ragTopK), observation hygiene in @Tool adapters, and—when you use @hazeljs/ai helpers—AIContextManager limits (maxTokens, reserveTokens).

Related: /learn/agentic-development/context-windows-as-scarce-resources, /patterns/memory-layers. Docs: Agent, AI.

Worked example — intentional flags

typescript
import { Agent, Tool, AgentRuntime } from '@hazeljs/agent';

@Agent({
  name: 'support-desk',
  systemPrompt: 'Help with order status. Prefer tools over guessing.',
  enableMemory: false, // default off unless the product needs session recall
  enableRAG: true,     // help-center grounding
  ragTopK: 5,
  maxSteps: 8,
})
export class SupportDesk {
  @Tool({
    description: 'Look up order by ID',
    parameters: [
      { name: 'orderId', type: 'string', required: true },
    ],
  })
  async lookupOrder(input: { orderId: string }) {
    const order = await orders.get(input.orderId);
    // Return a compact observation — not the raw ORM dump
    return {
      orderId: order.id,
      status: order.status,
      eta: order.eta,
      itemCount: order.items.length,
    };
  }
}

const result = await runtime.execute('support-desk', 'Where is ORD-1001?', {
  sessionId: 'user-42',
  enableRAG: true,   // can override per call
  enableMemory: false,
  ragTopK: 5,
  maxSteps: 8,
  budget: { maxTokens: 40_000, maxCostUsd: 0.25 },
});

Truncate in the adapter (not the prompt)

typescript
@Tool({ description: 'Fetch a support article by id' })
async getArticle(input: { id: string }) {
  const html = await cms.fetchHtml(input.id);
  const text = stripHtml(html).slice(0, 2_000); // hard cap before context assembly
  return { id: input.id, excerpt: text };
}

Design rules

  1. Prefer IDs + summaries over raw dumps in tool results.
  2. Turn RAG/memory on per call, not “always on.”
  3. Cap observation size in the adapter.
  4. Mask PII before content leaves your process (defaultPiiMaskPolicies / Guardrails).
  5. Persist stop reasons when context pressure causes early stops.

Artifact

Document for one agent: default flags, max observation chars, RAG corpus, owner for truncation policy.

Next

/learn/context-engineering/rag-and-truncation-policies

Artifact: Context assembly checklist + sample execute options for one agent

Sources

Related