External Tool Execution Toolkit

This example demonstrates how to execute toolkit-based tools outside of the agent using external tool execution. It shows how to create a custom toolkit with tools that require external execution.

Code

external_tool_execution_toolkit.py

"""🤝 Human-in-the-Loop: Execute a tool call outside of the agent

This example shows how to implement human-in-the-loop functionality in your Agno tools.
It shows how to:
- Use external tool execution to execute a tool call outside of the agent

Run `pip install openai agno` to install dependencies.
"""

import subprocess

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools import tool
from agno.tools.toolkit import Toolkit
from agno.utils import pprint


class ShellTools(Toolkit):
    def __init__(self, *args, **kwargs):
        super().__init__(
            tools=[self.list_dir],
            external_execution_required_tools=["list_dir"],
            *args,
            **kwargs,
        )

    def list_dir(self, directory: str):
        """
        Lists the contents of a directory.

        Args:
            directory: The directory to list.

        Returns:
            A string containing the contents of the directory.
        """
        return subprocess.check_output(f"ls {directory}", shell=True).decode("utf-8")


tools = ShellTools()

agent = Agent(
    model=OpenAIChat(id="gpt-5-mini"),
    tools=[tools],
    markdown=True,
)

run_response = agent.run("What files do I have in my current directory?")
if run_response.is_paused:
    for tool in run_response.tools_awaiting_external_execution:
        if tool.tool_name == "list_dir":
            print(f"Executing {tool.tool_name} with args {tool.tool_args} externally")
            # We execute the tool ourselves. You can also execute something completely external here.
            result = tools.list_dir(**tool.tool_args)  # type: ignore
            # We have to set the result on the tool execution object so that the agent can continue
            tool.result = result

    run_response = agent.continue_run(run_response=run_response)
    pprint.pprint_run_response(run_response)

Usage

1. Create a virtual environment

   Open the Terminal and create a python virtual environment.

   Mac

   python3 -m venv .venv
   source .venv/bin/activate
   
2. Install libraries

   pip install -U agno openai
   
3. Export your OpenAI API key

   Mac/Linux

     export OPENAI_API_KEY="your_openai_api_key_here"
   
4. Create a Python file

   Create a Python file and add the above code.

   touch external_tool_execution_toolkit.py
   
5. Run Agent

   Mac

   python external_tool_execution_toolkit.py
   
6. Find All Cookbooks

   Explore all the available cookbooks in the Agno repository. Click the link below to view the code on GitHub:

   Agno Cookbooks on GitHub