Docker

DockerTools gives an agent full control over Docker containers, images, volumes, and networks.

DockerTools enable an Agent to interact with Docker containers, images, volumes, and networks.

Prerequisites

The following example requires the docker and openai Python packages. You'll also need Docker installed and running on your system.

uv pip install agno docker openai

The Agent model uses an OpenAI key, separately from any toolkit provider credentials.

Set OpenAI Key

Set your OPENAI_API_KEY as an environment variable. You can get one from OpenAI.

export OPENAI_API_KEY=sk-***

Example

The following example creates an agent that can manage Docker resources:

cookbook/91_tools/docker_tools.py
import sys

from agno.agent import Agent

try:
    from agno.tools.docker import DockerTools

    docker_tools = DockerTools()

    docker_agent = Agent(
        name="Docker Agent",
        instructions=[
            "You are a comprehensive Docker management assistant.",
            "You can manage containers, images, volumes, and networks.",
        ],
        tools=[docker_tools],
        markdown=True,
    )

    docker_agent.print_response("List all running Docker containers", stream=True)
    docker_agent.print_response("Pull the latest nginx image", stream=True)
    docker_agent.print_response(
        "Run an nginx container named 'web-server' on port 8080", stream=True
    )

except ValueError as e:
    print(f"\n[ERROR] Docker Tool Error: {e}")
    print("\nTroubleshooting steps:")

    if sys.platform == "darwin":  # macOS
        print("1. Ensure Docker Desktop is running")
        print("2. Check Docker Desktop settings")
        print("3. Try running 'docker ps' in terminal to verify access")

    elif sys.platform == "linux":
        print("1. Check if Docker service is running:")
        print("   systemctl status docker")
        print("2. Make sure your user has permissions to access Docker:")
        print("   sudo usermod -aG docker $USER")

    elif sys.platform == "win32":
        print("1. Ensure Docker Desktop is running")
        print("2. Check Docker Desktop settings")

DockerTools registers all functions by default, including remove_container, remove_image, remove_volume, remove_network, and exec_in_container, which runs an arbitrary command inside a container. No function filter or confirmation requirement is applied by default. Use include_tools/exclude_tools to select functions and requires_confirmation_tools to gate calls through HITL.

For example, expose only container listing and command execution, with execution requiring confirmation:

DockerTools(
    include_tools=["list_containers", "exec_in_container"],
    requires_confirmation_tools=["exec_in_container"],
)

Toolkit Params

DockerTools registers all functions below by default. Limit them with the base toolkit params:

ParameterTypeDefaultDescription
include_toolsOptional[list[str]]NoneRegister only these function names
exclude_toolsOptional[list[str]]NoneSkip these function names

Toolkit Functions

Container Management

FunctionDescription
list_containersLists all containers or only running containers
start_containerStarts a stopped container
stop_containerStops a running container
remove_containerRemoves a container
get_container_logsRetrieves logs from a container
inspect_containerGets detailed information about a container
run_containerCreates and starts a new container
exec_in_containerExecutes a command inside a running container

Image Management

FunctionDescription
list_imagesLists all images on the system
pull_imagePulls an image from a registry
remove_imageRemoves an image
build_imageBuilds an image from a Dockerfile
tag_imageTags an image
inspect_imageGets detailed information about an image

Volume Management

FunctionDescription
list_volumesLists all volumes
create_volumeCreates a new volume
remove_volumeRemoves a volume
inspect_volumeGets detailed information about a volume

Network Management

FunctionDescription
list_networksLists all networks
create_networkCreates a new network
remove_networkRemoves a network
inspect_networkGets detailed information about a network
connect_container_to_networkConnects a container to a network
disconnect_container_from_networkDisconnects a container from a network

Developer Resources