Skip to main content
Tools extend an agent beyond conversation. When an agent needs to take an action — reading a file, running a shell command, or calling an API — it makes a tool call. Docker Agent executes the tool and returns the result, which the agent uses to continue its work.

​
How tool calls work

1

User sends a message

The agent receives the user’s request and reasons about what actions are needed.
2

Agent calls a tool

The agent emits a structured tool call (e.g., read_file(path="main.go")).
3

Docker Agent executes the tool

The runtime executes the tool and returns the result. By default, tools with side effects (writes, shell commands) require user confirmation first.
4

Agent continues

The agent incorporates the result and decides whether to call more tools or respond to the user.
Use --yolo to auto-approve all tool calls without prompts — useful for scripting and automated workflows:
docker agent run agent.yaml --yolo

​
Toolsets

Tools are grouped into toolsets — an array of tool configurations on each agent. Each toolset has a type that determines which tools are loaded:
agent.yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-0
    instruction: You are a coding assistant.
    toolsets:
      - type: filesystem
      - type: shell
      - type: think
      - type: mcp
        ref: docker:duckduckgo

​
Toolset fields

​
type
string
required
The toolset type. Determines which tools are loaded. See built-in toolsets and MCP toolsets.
​
instruction
string
Extra guidance added to the agent’s context about how and when to use tools in this toolset.
​
tools
string[]
Restrict which individual tools within this toolset are available to the agent.
​
model
string
Override the model used for the turn that processes tool results from this toolset. Useful for per-toolset model routing.

​
Built-in toolsets

Docker Agent ships with built-in toolsets that require no external dependencies:
Toolset typeDescription
filesystemRead, write, list, search, and navigate files and directories
shellExecute shell commands in the user’s environment
thinkStep-by-step reasoning scratchpad for planning and decision-making
todoTask list management for complex multi-step workflows
memoryPersistent key-value storage backed by SQLite
fetchMake HTTP requests to external APIs and web services
scriptDefine custom shell scripts as named tools
lspConnect to Language Server Protocol servers for code intelligence
apiCreate custom tools that call HTTP APIs without writing code
user_promptAsk users questions and collect interactive input
transfer_taskDelegate tasks to sub-agents (auto-enabled with sub_agents)
background_agentsDispatch work to sub-agents concurrently
handoffDelegate tasks to remote agents via A2A
a2aConnect to remote agents via the Agent-to-Agent protocol
See the Built-in Tools section for full configuration reference for each type.

​
Toolset-specific options

Some toolsets accept additional configuration fields: 
toolsets:
  - type: memory
    path: ./agent-memory.db  # path to the SQLite database file

​
MCP toolsets

Docker Agent supports the Model Context Protocol (MCP) for connecting external tool servers. There are three ways to connect an MCP server:

​
Reusable MCP definitions

Define MCP servers once in the top-level mcps section and reference them from multiple agents:
agent.yaml
mcps:
  search:
    ref: docker:duckduckgo
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${env.GITHUB_TOKEN}"

agents:
  researcher:
    toolsets:
      - type: mcp
        ref: search
      - type: mcp
        ref: github

​
Toolset instructions

Use the instruction field to give the agent extra guidance about a specific toolset:
agent.yaml
agents:
  root:
    toolsets:
      - type: filesystem
        instruction: |
          Only read files in the current working directory.
          Never modify files outside the project root.
      - type: shell
        instruction: |
          Prefer read-only commands when possible.
          Always confirm with the user before deleting anything.

​
Permissions

Control which tools are auto-approved, always require confirmation, or are blocked entirely:
agent.yaml
permissions:
  allow:
    - read_file        # always auto-approve file reads
    - list_directory
  ask:
    - write_file       # always ask even if --yolo is set
  deny:
    - shell            # block all shell execution
    - mcp:github:*     # block all GitHub MCP tools
The evaluation order is: deny first, then allow, then ask, then the default behavior (read-only tools auto-approved, others ask). Patterns support glob-style matching.
See Permissions for the full configuration reference.

​
Next steps

Built-in tools reference

Full reference for every built-in toolset.

Tool configuration

All toolset configuration options.

Permissions

Control tool approval behavior.

RAG

Add document retrieval to your agents.

Build docs developers (and LLMs) love

Get started for freeTalk to us