AutoGen Tutorial (TypeScript): adding tool use for beginners

This tutorial shows you how to add tool use to an AutoGen TypeScript agent so it can call real functions instead of only chatting. You need this when your agent has to fetch data, do calculations, or trigger internal workflows without hardcoding every response.

What You'll Need

• •Node.js 18+ installed
• •A TypeScript project initialized with npm init -y
• •AutoGen packages:
  • •npm install @autogen/core @autogen/openai
• •A valid OpenAI API key
• •A .env file or shell environment variable for OPENAI_API_KEY
• •Basic familiarity with AutoGen agents and async/await

Step-by-Step

1. •Create a small TypeScript project and install the dependencies.
   Keep this minimal so you can focus on the tool wiring first.

mkdir autogen-tool-use-demo
cd autogen-tool-use-demo
npm init -y
npm install @autogen/core @autogen/openai dotenv
npm install -D typescript tsx @types/node
npx tsc --init

2. •Add your API key and a simple TypeScript entry file.
   I prefer tsx for running examples during development because it avoids a compile step while still using TypeScript.

cat > .env <<'EOF'
OPENAI_API_KEY=your_openai_api_key_here
EOF

cat > index.ts <<'EOF'
import "dotenv/config";
import { OpenAIChatCompletionClient } from "@autogen/openai";
import { AssistantAgent, FunctionTool } from "@autogen/core";

async function main() {
  const modelClient = new OpenAIChatCompletionClient({
    model: "gpt-4o-mini",
    apiKey: process.env.OPENAI_API_KEY,
  });

  console.log("Ready:", !!process.env.OPENAI_API_KEY);
}

main().catch(console.error);
EOF

3. •Define a real tool as a normal TypeScript function, then wrap it with FunctionTool.
   The key idea is that AutoGen needs a typed function with a clear name and description so the model knows when to call it.

import "dotenv/config";
import { OpenAIChatCompletionClient } from "@autogen/openai";
import { AssistantAgent, FunctionTool } from "@autogen/core";

async function getExchangeRate(base: string, quote: string): Promise<string> {
  const rates: Record<string, number> = {
    "USD_EUR": 0.92,
    "USD_GBP": 0.79,
    "EUR_USD": 1.09,
  };

  const key = `${base}_${quote}`;
  const rate = rates[key];
  if (!rate) return `No rate found for ${base}/${quote}`;
  return `1 ${base} = ${rate} ${quote}`;
}

const exchangeRateTool = new FunctionTool(getExchangeRate, {
  name: "get_exchange_rate",
  description: "Get a sample FX exchange rate for common currency pairs.",
});

4. •Create an assistant agent and give it the tool in its configuration.
   This is the part beginners usually miss: the agent must be told which tools exist before it can decide to call them.

async function main() {
  const modelClient = new OpenAIChatCompletionClient({
    model: "gpt-4o-mini",
    apiKey: process.env.OPENAI_API_KEY,
  });

  const agent = new AssistantAgent({
    name: "finance_assistant",
    modelClient,
    tools: [exchangeRateTool],
    systemMessage:
      "You are a helpful assistant. Use tools when the user asks for exchange rates.",
  });

  console.log("Agent ready:", agent.name);
}

main().catch(console.error);

5. •Send a prompt that should trigger tool use, then print the result.
   If everything is wired correctly, the model will call your function and incorporate the output into its final answer.

import "dotenv/config";
import { OpenAIChatCompletionClient } from "@autogen/openai";
import { AssistantAgent, FunctionTool } from "@autogen/core";

async function getExchangeRate(base: string, quote: string): Promise<string> {
  const rates: Record<string, number> = {
    "USD_EUR": 0.92,
    "USD_GBP": 0.79,
    "EUR_USD": 1.09,
  };

  const key = `${base}_${quote}`;
  const rate = rates[key];
  if (!rate) return `No rate found for ${base}/${quote}`;
  return `1 ${base} = ${rate} ${quote}`;
}

const exchangeRateTool = new FunctionTool(getExchangeRate, {
  name: "get_exchange_rate",
});

async function main() {
  const modelClient = new OpenAIChatCompletionClient({
    model: "gpt-4o-mini",
    apiKey: process.env.OPENAI_API_KEY,
  });

  const agent = new AssistantAgent({
    name: "finance_assistant",
    modelClient,
    tools: [exchangeRateTool],
    systemMessage:
      "Use tools when asked about exchange rates.",
  });

  const result = await agent.run(
    "What is the USD to EUR exchange rate?"
  );

  console.log(result.messages.at(-1)?.content);
}

main().catch(console.error);

6. •Run the file and confirm tool invocation appears in the output or logs.
   If you want stronger proof, temporarily change the tool to return an obvious string like "TOOL CALLED" and verify that string shows up in the final response.

npx tsx index.ts

Testing It

Start with a prompt that clearly requires the tool, like “What is USD to EUR?” or “Get me the exchange rate for EUR/USD.” The agent should not invent a value if your system message pushes it toward using tools.

If you get an empty response or no tool call, check three things first: your API key is loaded, the tool is included in tools, and the function signature uses plain JSON-serializable arguments like strings and numbers. Also make sure your tool name is explicit and stable; vague names make planning worse.

For debugging, simplify the tool output so you can see exactly when it runs. Once that works, swap in your real implementation such as database reads, internal HTTP calls, or policy lookups.

Next Steps

• •Add multiple tools and learn how AutoGen chooses between them
• •Wrap real HTTP or database calls behind tools with timeout handling
• •Add structured outputs so downstream code can consume tool results safely

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.