Vercel AI SDK

// app/api/chat/route.ts
import {
  convertToModelMessages,
  streamText,
  stepCountIs,
  type UIMessage,
} from 'ai';
import { openai } from '@ai-sdk/openai';
import { nimbleSearch } from '@nimble-way/ai-sdk';

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: openai('gpt-5'),
    messages: await convertToModelMessages(messages),
    tools: {
      webSearch: nimbleSearch({ searchDepth: 'lite', maxResults: 5 }),
    },
    stopWhen: stepCountIs(5),
  });

  return result.toUIMessageStreamResponse();
}

{
  query: string;
  requestId?: string;
  totalResults?: number;
  results: Array<{
    title: string;
    url: string;
    description?: string;
    content?: string;     // deep searches only
    position?: number;
    entityType?: string;
  }>;
}

import { generateText, stepCountIs } from 'ai';
import { openai } from '@ai-sdk/openai';
import { nimbleExtract } from '@nimble-way/ai-sdk';

const { text } = await generateText({
  model: openai('gpt-5'),
  prompt: 'Summarize https://en.wikipedia.org/wiki/Web_scraping',
  tools: { extract: nimbleExtract({ format: 'markdown' }) },
  // Allow a step after the tool call so the model can read the page.
  stopWhen: stepCountIs(2),
});

console.log(text);

tools: {
  webSearch: nimbleSearch(),
  extract: nimbleExtract(),
}

{
  url: string;
  status: string;        // e.g. 'success'
  statusCode?: number;
  format: 'markdown' | 'html';
  content: string;       // truncated to maxContentLength
  links?: string[];
}

// Request 1: start the run. Returns without waiting for the research.
import { generateText, stepCountIs } from 'ai';
import { openai } from '@ai-sdk/openai';
import { nimbleAgentStartRun } from '@nimble-way/ai-sdk';
import type { NimbleAgentStartRunOutput } from '@nimble-way/ai-sdk';

const { text, steps } = await generateText({
  model: openai('gpt-5'),
  prompt:
    'Start deep research on the EU AI Act enforcement timeline, then tell ' +
    'the user research is underway and the answer takes a few minutes.',
  tools: { startResearch: nimbleAgentStartRun({ effort: 'medium' }) },
  stopWhen: stepCountIs(2),
});

// Pull the run ID out of the tool result and persist it.
const started = steps
  .flatMap((step) => step.toolResults)
  .find((result) => result.toolName === 'startResearch')?.output as
  | NimbleAgentStartRunOutput
  | undefined;

if (started) {
  // Persist the run ID however your app stores state: database,
  // session, or job queue. `saveRunId` here is your own function.
  await saveRunId(started.runId); // e.g. 'task_run_8f3c...'
}

{
  runId: 'task_run_8f3c...',   // pass this to the status and result tools
  agentId: 'wsa_01j9x8...',
  interactionId: 'int_...',
  status: 'queued',
  effort: 'medium',
  createdAt: '2026-07-31T10:00:00Z',
}

// Request 2: minutes later, a different request or process.
import { generateText, stepCountIs } from 'ai';
import { openai } from '@ai-sdk/openai';
import { nimbleAgentRunResult } from '@nimble-way/ai-sdk';
import type { NimbleAgentRunResultOutput } from '@nimble-way/ai-sdk';

const { text, steps } = await generateText({
  model: openai('gpt-5'),
  prompt:
    `The user is back. Fetch research run ${runId}. If it is not ready, say ` +
    `so briefly. If it is, answer from it and keep the citation callouts.`,
  tools: { getResearchResult: nimbleAgentRunResult() },
  stopWhen: stepCountIs(2),
});

const result = steps
  .flatMap((step) => step.toolResults)
  .find((r) => r.toolName === 'getResearchResult')?.output as
  | NimbleAgentRunResultOutput
  | undefined;

if (result?.ready) {
  const { confidence, sources, claims } = result.output.trust;
  console.log(`${confidence} confidence, ${sources.length} sources, ${claims.length} claims`);
}

tools: {
  startResearch: nimbleAgentStartRun({ effort: 'medium' }),
  checkResearch: nimbleAgentRunStatus(),
  getResearchResult: nimbleAgentRunResult(),
}

{
  ready: false,
  runId: 'task_run_8f3c...',
  agentId: 'wsa_01j9x8...',
  status: 'running',        // or 'queued'
  isActive: true,
  effort: 'medium',
  createdAt: '2026-07-31T10:00:00Z',
  startedAt: '2026-07-31T10:00:01Z',
}

{
  ready: true;
  runId: string;
  agentId: string;
  status: 'completed';
  effort: 'low' | 'medium' | 'high' | 'x-high' | 'max';
  createdAt: string;
  startedAt?: string;
  completedAt?: string;
  output:
    | { type: 'text'; text: string; trust: NimbleAgentTrust }
    | { type: 'json'; json: object | unknown[]; trust: NimbleAgentTrust };
}

{
  confidence: 'high' | 'medium' | 'low' | 'pre_existing';
  reasoning: string;
  sources: Array<{
    url: string;
    type: 'primary' | 'secondary';
    title?: string;
    source_category?: 'official' | 'news' | 'social' | 'academic' | 'aggregator' | 'other';
  }>;
  claims: Array<{
    callout?: number;   // text answers: the [1]-style marker in the prose
    path?: string;      // json answers: the JSON path of the value
    confidence: 'high' | 'medium' | 'low' | 'pre_existing';
    reasoning: string;
    citations: Array<{ url: string; title?: string; excerpts?: string[] }>;
  }>;
}