How to Build an AI Agent with TypeScript

Install ai (the Vercel AI SDK) and zod, which the SDK uses for tool input validation. Export your provider's API key as an environment variable; the SDK's provider strings read it the same way the underlying client would. Model strings in v7 are provider-agnostic: 'anthropic/claude-sonnet-5.5' or 'openai/gpt-6.1-sol' both work with the same agent code.

1npm i ai zod
2export ANTHROPIC_API_KEY="sk-ant-..."

Each tool's inputSchema is a Zod object. z.object({...}).describe() comments give the model extra context on top of the tool's own description. Define checkDeployStatus (takes a service name) and postIncidentSummary (takes a service name and a summary string).

1import { z } from 'zod';
2
3const checkDeployStatusInput = z.object({
4  service: z.string().describe('The service name, e.g. checkout-service'),
5});
6
7const postIncidentSummaryInput = z.object({
8  service: z.string(),
9  summary: z.string().describe('A one-paragraph incident summary'),
10});

tool() takes a description, the inputSchema, and an async execute function whose parameter is fully typed from that schema, no casting required. checkDeployStatus returns a mock status object here; in production it calls your deployment platform's API. postIncidentSummary would call the Slack API's chat.postMessage.

1import { tool } from 'ai';
2
3const checkDeployStatus = tool({
4  description: 'Check the current deployment status for a service.',
5  inputSchema: checkDeployStatusInput,
6  execute: async ({ service }) => {
7    return { service, status: 'degraded', errorRatePct: 12.4 };
8  },
9});
10
11const postIncidentSummary = tool({
12  description: 'Post an incident summary to the #incidents Slack channel.',
13  inputSchema: postIncidentSummaryInput,
14  execute: async ({ service, summary }) => {
15    // await slackClient.chat.postMessage({ channel: '#incidents', text: summary });
16    return { posted: true, service };
17  },
18});

Instantiate ToolLoopAgent with a model string, instructions (the v7 name for what used to be called system), the tools map, and stopWhen: isStepCount(n) so a confused agent fails after a fixed number of steps instead of looping indefinitely. 10 is a reasonable default for a two-tool agent.

1import { ToolLoopAgent, isStepCount } from 'ai';
2
3const agent = new ToolLoopAgent({
4  model: 'anthropic/claude-sonnet-5.5',
5  instructions:
6    'You are an on-call ops assistant. Always check deploy status before ' +
7    'posting a summary. Only post a summary if the status is degraded or worse.',
8  tools: { checkDeployStatus, postIncidentSummary },
9  stopWhen: isStepCount(10),
10});

agent.generate() runs the loop and returns an object with text (the final answer), steps (every step the agent took, including tool calls and their results), and more. Use result.steps when you need to show or log what happened, not just the final text.

1const result = await agent.generate({
2  prompt: 'Check checkout-service and post a summary if anything is wrong.',
3});
4
5console.log(result.text);
6console.log(`${result.steps.length} steps taken`);

For a UI that shows progress live, call agent.stream() instead of generate() and consume the stream. Wrap each tool's execute() in try/catch so a failed Slack call or API timeout returns a typed error object instead of throwing into the loop. In a Next.js app, wrap this whole agent in a Route Handler (app/api/incident-check/route.ts) rather than calling it from a Client Component, so your API key never ships to the browser.

1export async function POST(req: Request) {
2  const { service } = await req.json();
3  const result = await agent.generate({ prompt: `Check ${service} and post a summary if degraded.` });
4  return Response.json({ text: result.text, steps: result.steps.length });
5}