Next.js

05 Tools and Context

Scope Next.js request data before exposing tools and retrieval to Anvia.

If a tool needs the current user, build a request-scoped tool or agent factory. Keep provider clients and models reusable.

1. Create a Scoped Agent Factory

import { AgentBuilder, createTool } from "@anvia/core";
import { z } from "zod";
import { model } from "@/app/ai/support-agent";
import { orders } from "@/app/db/orders";

type SupportScope = {
  userId: string;
};

export function createSupportAgent(scope: SupportScope) {
  const lookupOrder = createTool({
    name: "lookup_order",
    description: "Look up one order owned by the current user.",
    input: z.object({
      orderId: z.string(),
    }),
    output: z.object({
      status: z.string(),
    }),
    async execute({ orderId }) {
      return orders.findForUser(scope.userId, orderId);
    },
  });

  return new AgentBuilder("support", model)
    .instructions("Use tools for account-specific data.")
    .tool(lookupOrder)
    .defaultMaxTurns(3)
    .build();
}

2. Resolve Auth In The Route

import { createSupportAgent } from "@/app/ai/create-support-agent";
import { requireUser } from "@/app/auth";

export async function POST(request: Request): Promise<Response> {
  const user = await requireUser(request);
  const { message } = (await request.json()) as { message?: string };

  if (!message?.trim()) {
    return Response.json({ error: "message is required" }, { status: 400 });
  }

  const agent = createSupportAgent({ userId: user.id });
  const response = await agent.prompt(message).send();

  return Response.json({ output: response.output });
}

3. Add Retrieval Context

const agent = new AgentBuilder("support", model)
  .instructions("Use retrieved support docs when relevant.")
  .dynamicContext(supportDocsIndex, {
    topK: 3,
    threshold: 0.7,
  })
  .tool(lookupOrder)
  .build();

Build the retrieval index outside hot request paths. Use request-scoped tools for permissions and retrieval context for searchable knowledge.

Next

Persist conversations in Persistence. Related guides: Runtime Context, RAG Context, and Tool Handlers.