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

This tutorial shows you how to build a custom AutoGen tool in Python, register it with an assistant agent, and let the model call it through normal chat. You need this when the built-in examples are too simple and you want deterministic business logic like formatting, validation, or data lookup wrapped as a callable tool.

What You'll Need

• •Python 3.10+
• •pyautogen installed
• •An OpenAI API key set in your environment
• •A working AutoGen setup with AssistantAgent and UserProxyAgent
• •Basic familiarity with Python functions and decorators
• •Optional: access to a local service or database if you want to replace the sample tool later

Step-by-Step

1. •Start by installing the package and setting your API key. I’m using the current AutoGen Python package name and a standard environment variable for the OpenAI key.

pip install pyautogen
export OPENAI_API_KEY="your-api-key-here"

2. •Define a real Python function that will act as your tool. Keep it deterministic, typed, and side-effect free at first; that makes it much easier for the model to use reliably.

from typing import List

def summarize_transactions(transactions: List[float]) -> dict:
    if not transactions:
        return {"count": 0, "total": 0.0, "average": 0.0}

    total = sum(transactions)
    count = len(transactions)
    average = total / count

    return {
        "count": count,
        "total": round(total, 2),
        "average": round(average, 2),
    }

3. •Create your agents and register the function as a tool on the user proxy side. The function_map is what lets AutoGen execute your Python function when the assistant requests it.

import os
from autogen import AssistantAgent, UserProxyAgent

config_list = [
    {
        "model": "gpt-4o-mini",
        "api_key": os.environ["OPENAI_API_KEY"],
    }
]

assistant = AssistantAgent(
    name="assistant",
    llm_config={"config_list": config_list},
)

user_proxy = UserProxyAgent(
    name="user_proxy",
    human_input_mode="NEVER",
    code_execution_config=False,
)

user_proxy.register_function(
    function_map={
        "summarize_transactions": summarize_transactions,
    }
)

4. •Tell AutoGen exactly how to use the tool by describing it in the system message. The model needs a clear contract: what inputs it expects and what output shape it returns.

assistant.system_message = """
You are a finance assistant.
When asked to analyze transaction amounts, call summarize_transactions.
Input must be a JSON-like list of numbers.
Return the tool result directly and explain it briefly.
"""

5. •Run a conversation where the assistant can decide to call the tool. In production, this is where you’d connect your own business function: fraud scoring, policy lookup, KYC checks, claims enrichment, or ledger summaries.

message = """
Summarize these transaction amounts:
[120.50, 89.99, 250.00, 15.25]
"""

result = user_proxy.initiate_chat(
    assistant,
    message=message,
)

print(result)

6. •If you want stronger control over tool behavior, add input validation before doing any work. This is important in bank and insurance workflows where malformed inputs should fail fast instead of producing garbage output.

def summarize_transactions_safe(transactions):
    if not isinstance(transactions, list):
        raise TypeError("transactions must be a list of numbers")

    if not all(isinstance(x, (int, float)) for x in transactions):
        raise ValueError("all transactions must be numeric")

    return summarize_transactions([float(x) for x in transactions])

Testing It

Run the script and confirm that AutoGen returns a response that includes the summary from your function: count, total, and average. If the model does not call the tool, tighten the system message so it explicitly names the function and its expected input format.

Test edge cases next: an empty list, strings inside the list, and very large lists. You should see either clean summaries or clear exceptions from your validation layer.

If you’re integrating this into an agent workflow with multiple tools, log each function invocation so you can trace which tool was selected and why. That matters when debugging model behavior in production.

Next Steps

• •Add more tools with distinct responsibilities: lookup_customer, validate_policy_number, calculate_premium
• •Learn AutoGen group chat patterns so multiple agents can coordinate around your tools
• •Wrap external systems behind thin Python functions so your agent only talks to stable interfaces

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.