Skip to content

Toolkits#

A Toolkit groups related tools into a single, reusable unit. Instead of passing individual tools one by one, you can bundle them into a toolkit and pass the whole collection to an agent. This is useful for organizing domain-specific capabilities (e.g., all database tools, all file-system tools) and sharing them across multiple agents.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
from ag2 import Agent
from ag2.tools import Toolkit

def search_orders(query: str) -> str:
    """Searches the order database."""
    return "Order #123"

def cancel_order(order_id: str) -> str:
    """Cancels an order by its ID."""
    return f"Order {order_id} cancelled."

support_tools = Toolkit(search_orders, cancel_order)

agent = Agent(name="SupportBot", tools=[support_tools])

A toolkit accepts both plain functions and @tool-decorated functions in its tools list. Plain functions are automatically converted, just like when passing them directly to an agent.

Registering Tools via a Decorator#

You can also add tools to a toolkit using the @toolkit.tool decorator, following the same pattern as @agent.tool:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
from ag2.tools import Toolkit

inventory = Toolkit()

@inventory.tool
def check_stock(item_id: str) -> int:
    """Returns the current stock count for an item."""
    return 42

@inventory.tool(
    name="reorder_item",
    description="Places a reorder for a low-stock item.",
)
def reorder(item_id: str, quantity: int) -> str:
    return f"Reordered {quantity} of {item_id}."

The toolkit can then be passed to any number of agents:

1
2
3
4
from ag2 import Agent

warehouse_agent = Agent(name="WarehouseBot", tools=[inventory])
sales_agent = Agent(name="SalesBot", tools=[inventory])

Combining Toolkits with Standalone Tools#

You can freely mix toolkits and individual tools in an agent's tools list:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from ag2 import tool

@tool
def escalate(reason: str) -> str:
    """Escalates the conversation to a human agent."""
    return "Escalated."

agent = Agent(
    name="SupportBot",
    tools=[support_tools, inventory, escalate],
)

Toolkit middleware#

Pass middleware=[...] to the Toolkit constructor to apply hooks to every tool in the set — both tools passed to the constructor and tools added later via @toolkit.tool:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from ag2 import Context
from ag2.events import ToolCallEvent, ToolResultEvent
from ag2.middleware import ToolExecution
from ag2.tools import Toolkit

async def log_calls(
    call_next: ToolExecution, event: ToolCallEvent, context: Context,
) -> ToolResultEvent:
    print(f"Calling {event.name}")
    return await call_next(event, context)

support_tools = Toolkit(search_orders, cancel_order, middleware=[log_calls])

Toolkit middleware is the outermost layer: it runs before any per-tool middleware defined with @tool(middleware=[...]).

Per-tool middleware#

@toolkit.tool also accepts the same middleware=[...] option as @tool and @agent.tool. These per-tool hooks run inside the toolkit-level middleware. See Tool middleware.