AutoGen Tutorial (TypeScript): building custom tools for intermediate developers

This tutorial shows you how to build a custom AutoGen tool in TypeScript, register it with an agent, and use it in a real conversation flow. You need this when the built-in tools are not enough and you want your agent to call your own business logic, internal APIs, or validation code.

What You'll Need

• •Node.js 18+
• •TypeScript 5+
• •An OpenAI API key
• •npm or pnpm
• •AutoGen for TypeScript packages:
  • •@autogenai/autogen
  • •openai
  • •zod
• •A .env file with:
  • •OPENAI_API_KEY=...

Step-by-Step

1. •Start by creating a small TypeScript project and installing the dependencies. Keep the setup minimal so you can focus on the tool contract instead of framework glue.

mkdir autogen-custom-tools
cd autogen-custom-tools
npm init -y
npm install @autogenai/autogen openai zod dotenv
npm install -D typescript tsx @types/node
npx tsc --init

2. •Define a custom tool as a normal async function with explicit input validation. For production use, keep the tool deterministic, narrow in scope, and easy to test outside the agent.

// tools.ts
import { z } from "zod";

export const policyLookupInput = z.object({
  policyNumber: z.string().min(5),
});

export type PolicyLookupInput = z.infer<typeof policyLookupInput>;

export async function lookupPolicy(input: PolicyLookupInput) {
  const normalized = input.policyNumber.trim().toUpperCase();

  return {
    policyNumber: normalized,
    status: "active",
    premiumDueDate: "2026-05-01",
    outstandingBalance: 0,
  };
}

3. •Create an AutoGen assistant and register the tool so the model can call it. The important part is exposing a clean schema; AutoGen uses that schema to decide when and how to invoke your function.

// agent.ts
import "dotenv/config";
import OpenAI from "openai";
import { AssistantAgent } from "@autogenai/autogen";
import { lookupPolicy, policyLookupInput } from "./tools.js";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

export const assistant = new AssistantAgent({
  name: "insurance_assistant",
  modelClient: client,
  systemMessage:
    "You help users check policy status. Use tools when policy data is needed.",
});

assistant.registerTool(
  {
    name: "lookup_policy",
    description: "Look up an insurance policy by policy number.",
    parameters: policyLookupInput,
  },
  async (input) => lookupPolicy(input)
);

4. •Add a runner that sends a user message and lets the agent decide whether to call the tool. This is where you verify the end-to-end flow, not just the standalone function.

// index.ts
import { assistant } from "./agent.js";

async function main() {
  const result = await assistant.run({
    messages: [
      {
        role: "user",
        content: "Check policy ABC12345 and tell me if it is active.",
      },
    ],
  });

  console.log(JSON.stringify(result, null, 2));
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

5. •Run it with TypeScript execution and inspect whether the agent used your tool. If everything is wired correctly, you should see a response grounded in the tool output rather than a hallucinated answer.

{
  "type": "module"
}

npx tsx index.ts

Testing It

Verify two things first: that lookupPolicy() works directly, and that the agent can call it through natural language. If direct invocation passes but agent invocation fails, the issue is usually in the schema shape or registration wiring.

Try changing the user prompt to something ambiguous like “What’s going on with my policy?” and confirm the model asks for a policy number instead of inventing one. Then test an invalid input such as AB1 and make sure your validation rejects it before any downstream call happens.

For production debugging, log both the incoming tool arguments and returned payloads. That gives you a clean audit trail when an agent produces unexpected behavior.

Next Steps

• •Add more tools with different schemas, then compare when the model chooses each one.
• •Wrap internal HTTP APIs as tools and add retries, timeouts, and circuit breakers.
• •Move from simple responses to structured outputs so downstream systems can consume results without parsing text.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.