Ground an agent before it acts

Gather context, check its evidence coverage, and confirm it is fit to act on before letting an agent proceed.

The point of structured knowledge is that an agent can reason over it with control. This guide wires the read surfaces into a gate: gather context, confirm it is grounded in real sources, and check it is sufficient for the task before the agent acts.

search / recall ──▶ trace (is it grounded?) ──▶ check (is it sufficient?) ──▶ act or repair

Prerequisite: a client. Nothing in this guide writes to the graph.

1. Gather context

   Pull what the agent needs from the graph, and synthesize recalled memory into a briefing.

   const hits = await pb.search("Acme renewal status and open risks", {
     include: ["entities", "chunks"],
     limit: 10,
   });
   
   const briefing = await pb.memory.synthesize({
     query: "what should be known before contacting Acme?",
     as: { type: "SituationBriefing", purpose: "agent-handoff" },
   });
   
2. Trace evidence coverage

   Confirm the briefing is grounded in stored sources, not inferred. Pass it straight to pb.dq.trace.

   const trace = await pb.dq.trace(briefing);
   
   if (!trace.grounded) {
     console.log("Unsupported claims:", trace.unsupported);
   }
   

   Each claim is marked supported (backed by a stored source), inferred (related but not directly sourced), or unsupported.

3. Check it is fit to act on

   Ask whether the subject is sufficient for the specific thing the agent is about to do. The verdict is a disposition plus findings, never a score.

   const verdict = await pb.dq.check({
     subject: { type: "Account", id: "acme" },
     purpose: "send a renewal proposal",
   });
   
4. Act or repair

   Let the agent proceed only on a clean verdict. Otherwise turn the findings into remediation steps and fill the gaps first.

   if (verdict.safeToAct && trace.grounded) {
     // proceed
   } else {
     console.log(verdict.explain());
     const plan = pb.dq.repair(verdict); // what to hydrate, capture, or extract
     // run the steps via pb.* , then re-check
   }
   

Why this matters

An agent acting on ungrounded or insufficient context fails quietly. Putting a trace and check in front of the action turns “the model was confident” into “the graph was sufficient and sourced,” which is something you can audit.

Decision quality

Dispositions, findings, and repair.

Memory

Remember, recall, and synthesize.