AutoGen Tutorial (TypeScript): testing agents locally for beginners

This tutorial shows you how to run and test an AutoGen agent locally in TypeScript without wiring up a full app first. You need this when you want to verify prompts, tool calls, and message flow before shipping agents into a bank or insurance workflow.

What You'll Need

• •Node.js 18+ installed
• •A TypeScript project initialized with npm init -y
• •AutoGen packages:
  • •@autogen/core
  • •@autogen/openai
  • •@autogen/extensions
• •An OpenAI API key set in your environment as OPENAI_API_KEY
• •ts-node or tsx for running TypeScript locally
• •Basic familiarity with async/await and ES modules

Step-by-Step

1. •Create a small TypeScript project and install the packages. Keep this minimal so you can test one agent loop at a time before adding tools or multi-agent routing.

mkdir autogen-local-test
cd autogen-local-test
npm init -y
npm install @autogen/core @autogen/openai @autogen/extensions dotenv
npm install -D typescript tsx @types/node
npx tsc --init --module nodenext --moduleResolution nodenext --target es2022 --strict

2. •Add your environment variable and a simple script entry point. For local testing, I prefer loading env vars from .env so the same code works on your laptop and in CI.

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

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

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

  const agent = new AssistantAgent({
    name: "local_tester",
    modelClient,
    systemMessage: "You are a concise assistant that answers in one sentence.",
  });

  const result = await agent.run("What is the purpose of local agent testing?");
  console.log(result.messages.at(-1)?.content);
}

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

3. •Run the agent locally and confirm you get a response back. This is the fastest way to validate that your API key, model client, and agent wiring are all correct.

npx tsx index.ts

4. •Add a tool so you can test deterministic behavior, not just free-form text generation. In real projects, this is where you verify things like policy lookups, claim status checks, or customer data transforms.

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

const getPolicyStatus = tool(
  async ({ policyId }: { policyId: string }) => {
    return { policyId, status: "active" };
  },
  {
    name: "get_policy_status",
    description: "Returns the status of an insurance policy.",
    parameters: {
      type: "object",
      properties: {
        policyId: { type: "string" },
      },
      required: ["policyId"],
      additionalProperties: false,
    },
  }
);

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

  const agent = new AssistantAgent({
    name: "policy_agent",
    modelClient,
    systemMessage: "Use tools when needed. Return short answers.",
    tools: [getPolicyStatus],
  });

  const result = await agent.run("Check policy ABC123.");
  console.log(JSON.stringify(result.messages, null, 2));
}

main().catch(console.error);

5. •Add a local assertion so you can treat the script like a test instead of a manual demo. For beginners, this is enough to catch broken prompts or tool registration before you move into a proper test runner.

import "dotenv/config";
import assert from "node:assert/strict";
import { AssistantAgent } from "@autogen/core";
import { OpenAIChatCompletionClient } from "@autogen/openai";

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

  const agent = new AssistantAgent({
    name: "assert_agent",
    modelClient,
    systemMessage: "Answer with exactly one short sentence.",
  });

  const result = await agent.run("Say hello.");
  const lastMessage = result.messages.at(-1)?.content ?? "";

  assert.ok(typeof lastMessage === "string");
  assert.ok(lastMessage.length > 0);

  console.log("Local test passed:", lastMessage);
}

main().catch(console.error);

Testing It

Run the script twice with slightly different prompts and compare the output shape, not just the wording. You want to confirm the agent returns messages consistently, tool calls happen when expected, and your assertions fail when you break something on purpose.

If the script fails immediately, check three things first:

• •OPENAI_API_KEY is loaded in the process
• •Your package versions match each other
• •You are using Node.js ESM-compatible settings with nodenext

For deeper validation, change the system message or tool schema and rerun. If the behavior changes predictably, your local test setup is working.

Next Steps

• •Add Jest or Vitest so these checks run in CI instead of only through tsx
• •Test multi-agent conversations with explicit handoff rules
• •Mock model responses for deterministic unit tests around tool execution

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.