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.

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:

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:

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:

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=[...]).

Combining tools with left | right creates a new toolkit containing the existing tools and their middleware. Each tool keeps its own hooks, and the source toolkits are unchanged. The combined toolkit has no middleware inherited from either side, so tools added later via @toolkit.tool use only the middleware explicitly supplied for them. If both sides contain a tool with the same name, the right-hand tool replaces the left-hand tool with its existing hooks.

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.