AutoGen Tutorial (Python): adding tool use for intermediate developers

This tutorial shows how to add tool use to an AutoGen Python agent so it can call real functions instead of just chatting. You need this when your agent must fetch data, transform inputs, or trigger internal workflows without hardcoding every response.

What You'll Need

• •Python 3.10+
• •autogen-agentchat
• •autogen-ext
• •An OpenAI API key
• •Basic familiarity with AutoGen agents and conversations
• •A terminal and a virtual environment

Install the packages first:

pip install autogen-agentchat autogen-ext openai

Set your API key in the environment:

export OPENAI_API_KEY="your-api-key"

Step-by-Step

1. •Start by defining a real tool function. Keep it deterministic, typed, and side-effect free for your first pass, because you want to verify the agent can call it correctly before wiring in external systems.

from typing import Annotated

def get_invoice_status(invoice_id: Annotated[str, "Invoice ID like INV-1001"]) -> str:
    invoices = {
        "INV-1001": "paid",
        "INV-1002": "pending",
        "INV-1003": "overdue",
    }
    return invoices.get(invoice_id, "not_found")

2. •Create an assistant agent with model configuration. This is the part that lets AutoGen talk to the LLM and decide when a tool should be called.

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient

model_client = OpenAIChatCompletionClient(
    model="gpt-4o-mini",
)

assistant = AssistantAgent(
    name="support_agent",
    model_client=model_client,
    system_message=(
        "You are a support assistant. "
        "Use tools when you need invoice status details."
    ),
)

3. •Register the tool with the agent. AutoGen uses type hints and docstrings to expose the function to the model, so make both clear and specific.

assistant.register_for_llm(name="get_invoice_status", description="Get the current status of an invoice")(get_invoice_status)
assistant.register_for_execution(name="get_invoice_status")(get_invoice_status)

4. •Run a chat that forces a tool decision. The user message should ask for something the model cannot answer from memory alone, which makes it obvious whether tool use is working.

async def main() -> None:
    result = await assistant.run(task="What is the status of invoice INV-1002?")
    print(result.messages[-1].content)

if __name__ == "__main__":
    asyncio.run(main())

5. •Add a second tool if you want to see how AutoGen handles multiple functions. In production, this is where you split responsibilities cleanly: one tool for lookup, another for formatting or validation.

def format_invoice_summary(
    invoice_id: Annotated[str, "Invoice ID"],
    status: Annotated[str, "Invoice status"],
) -> str:
    return f"Invoice {invoice_id} is currently {status}."

assistant.register_for_llm(name="format_invoice_summary", description="Format an invoice summary")(format_invoice_summary)
assistant.register_for_execution(name="format_invoice_summary")(format_invoice_summary)

Testing It

Run the script and confirm the final answer contains pending for INV-1002. If the model responds with a generic guess instead of calling the function, your tool registration or model setup is wrong.

Try at least two more inputs: one valid invoice ID and one unknown ID like INV-9999. You should see paid for known IDs and not_found for unknown ones.

If you want stronger verification, log tool calls by wrapping your function with a print statement or using your app logger. In production, that trace is what tells you whether the agent used tools correctly or hallucinated an answer.

Next Steps

• •Add argument validation with Pydantic before calling internal systems
• •Replace the in-memory dictionary with a real API or database lookup
• •Learn how to build multi-agent workflows where one agent plans and another executes tools

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.