### Setup and Run vLLM Server

Source: https://github.com/docker/docker-agent/blob/main/docs/providers/local/index.md

Install vLLM using pip and start the OpenAI-compatible API server. Specify the model to serve and the port.

```bash
# Install vLLM
pip install vllm

# Start the server
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.2-3B-Instruct \
  --port 8000
```

--------------------------------

### Starting Docker Agent Chat Server with Open WebUI Integration

Source: https://github.com/docker/docker-agent/blob/main/docs/features/chat-server/index.md

Example of starting the chat server with specific configurations for Open WebUI integration, including listen address, CORS origin, and API key environment variable.

```bash
$ docker agent serve chat agent.yaml \
    --listen 127.0.0.1:8083 \
    --cors-origin http://localhost:3000 \
    --api-key-env OPEN_WEBUI_TOKEN
```

--------------------------------

### Quick Start: Start Server, List Models, Send Chat Request

Source: https://github.com/docker/docker-agent/blob/main/docs/features/chat-server/index.md

Demonstrates the basic steps to start the chat server, list the exposed models using curl, and send a simple chat completion request.

```bash
# 1. Start the server
$ docker agent serve chat agent.yaml
Listening on 127.0.0.1:8083
OpenAI-compatible chat completions endpoint: http://127.0.0.1:8083/v1/chat/completions

# 2. List exposed agents (models)
$ curl http://127.0.0.1:8083/v1/models
{"object":"list","data":[{"id":"root","object":"model","owned_by":"docker-agent"}]}

# 3. Send a chat request
$ curl http://127.0.0.1:8083/v1/chat/completions \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "root",
      "messages": [{"role": "user", "content": "Hello!"}]
    }'
```

--------------------------------

### Start the API Server

Source: https://github.com/docker/docker-agent/blob/main/docs/features/api-server/index.md

Starts the API server with a specified agent configuration file.

```bash
# Start the API server
$ docker agent serve api agent.yaml
```

```bash
# Custom listen address
$ docker agent serve api agent.yaml --listen 0.0.0.0:8080
```

```bash
# With session persistence
$ docker agent serve api agent.yaml --session-db ./sessions.db
```

```bash
# Auto-refresh from OCI registry every 10 minutes
$ docker agent serve api agentcatalog/coder --pull-interval 10
```

--------------------------------

### Prepare Worktree with Dotfiles and Dependencies

Source: https://github.com/docker/docker-agent/blob/main/docs/configuration/hooks/index.md

Use the 'worktree_create' hook to copy untracked dotfiles like .env and install project dependencies within a new worktree. The hook runs inside the new worktree, allowing direct manipulation of the checkout. Abort the run by returning '{"continue": false}' or exiting with code 2 if setup fails.

```yaml
hooks:
  worktree_create:
    # Copy untracked dotfiles git won't bring into the new worktree.
    - name: seed local env
      type: command
      command: |
        INPUT=$(cat)
        SRC=$(echo "$INPUT" | jq -r '.worktree_source_dir // ""')
        [ -n "$SRC" ] && [ -f "$SRC/.env" ] && [ ! -f .env ] && cp "$SRC/.env" .env
        echo "Prepared worktree"
    # Install dependencies, aborting the run on failure.
    - name: install dependencies
      type: command
      timeout: 600
      command: |
        if [ -f package.json ]; then
          npm install || { echo '{"continue": false, "system_message": "npm install failed"}'; exit 2; }
        fi
```

--------------------------------

### Basic Go Agent Example

Source: https://github.com/docker/docker-agent/blob/main/docs/guides/go-sdk/index.md

This example demonstrates how to create a simple agent, configure it with a language model, and run it with a user message. It includes setting up context for graceful shutdown and handling potential errors.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os/signal"
    "syscall"

    "github.com/docker/docker-agent/pkg/agent"
    "github.com/docker/docker-agent/pkg/config/latest"
    "github.com/docker/docker-agent/pkg/environment"
    "github.com/docker/docker-agent/pkg/model/provider/openai"
    "github.com/docker/docker-agent/pkg/runtime"
    "github.com/docker/docker-agent/pkg/session"
    "github.com/docker/docker-agent/pkg/team"
)

func main() {
    ctx, cancel := signal.NotifyContext(context.Background(),
        syscall.SIGINT, syscall.SIGTERM)
    defer cancel()

    if err := run(ctx); err != nil {
        log.Fatal(err)
    }
}

func run(ctx context.Context) error {
    // Create model provider
    llm, err := openai.NewClient(
        ctx,
        &latest.ModelConfig{
            Provider: "openai",
            Model:    "gpt-4o",
        },
        environment.NewDefaultProvider(),
    )
    if err != nil {
        return err
    }

    // Create agent
    assistant := agent.New(
        "root",
        "You are a helpful assistant.",
        agent.WithModel(llm),
        agent.WithDescription("A helpful assistant"),
    )

    // Create team and runtime
    t := team.New(team.WithAgents(assistant))
    rt, err := runtime.New(t)
    if err != nil {
        return err
    }

    // Run with a user message
    sess := session.New(
        session.WithUserMessage("What is 2 + 2?"),
    )

    messages, err := rt.Run(ctx, sess)
    if err != nil {
        return err
    }

    // Print the response
    fmt.Println(messages[len(messages)-1].Message.Content)
    return nil
}

```

--------------------------------

### Verify Docker Agent Installation

Source: https://github.com/docker/docker-agent/blob/main/docs/getting-started/installation/index.md

Verify the installation by checking the agent's version and running the default agent or a built-in example. These commands confirm that the agent is installed correctly and operational.

```bash
# Check the version
$ docker agent version
```

```bash
# Run the default agent
$ docker agent run
```

```bash
# Or try a built-in example
$ docker agent run agentcatalog/pirate
```

--------------------------------

### Example Docker MCP Toolset Configuration

Source: https://github.com/docker/docker-agent/blob/main/docs/configuration/tools/index.md

This example demonstrates configuring a toolset with Docker MCP tools, referencing pre-defined tools like 'duckduckgo' for web search and 'github-official' for GitHub integration.

```yaml
toolsets:
  - type: mcp
    ref: docker:duckduckgo # web search
  - type: mcp
    ref: docker:github-official # GitHub integration
```

--------------------------------

### Run a Docker Agent Example

Source: https://github.com/docker/docker-agent/blob/main/examples/README.md

The standard command to run any agent example from the command line. Options include specifying a command, skipping the TUI, or running a specific agent from a multi-agent file.

```console
$ docker agent run examples/<name>.yaml

```

--------------------------------

### Example Tasks Toolset Configuration in Agent

Source: https://github.com/docker/docker-agent/blob/main/docs/tools/tasks/index.md

Example of how to configure the tasks toolset within an agent's configuration, specifying a custom database path.

```yaml
agents:
  root:
    model: openai/gpt-4o
    toolsets:
      - type: tasks
        path: ./project-tasks.json
```

--------------------------------

### Agent Example: Deploy to Staging

Source: https://github.com/docker/docker-agent/blob/main/docs/tools/user-prompt/index.md

Illustrates an agent using the user_prompt tool to ask for deployment environment and confirm the action.

```text
Agent: I need to deploy this application. Let me ask which environment to target.

[Calls user_prompt with message: "Which environment should I deploy to?"
 and schema with enum: ["development", "staging", "production"]]

User selects: "staging"

Agent: Great, I'll deploy to staging. Let me confirm this action.

[Calls user_prompt with message: "Deploy to staging? This will replace the current version."
 and schema with type: "boolean"]

User confirms: true

Agent: Deploying to staging...
```

--------------------------------

### Combined Agent Configuration Example

Source: https://github.com/docker/docker-agent/blob/main/docs/configuration/tools/index.md

A comprehensive example showing the integration of various toolsets, including built-in, custom scripts, API tools, and both local and remote MCP toolsets.

```yaml
agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Full-featured developer assistant
    instruction: You are an expert developer.
    toolsets:
      # Built-in tools
      - type: filesystem
      - type: shell
      - type: think
      - type: todo
      - type: memory
        path: ./dev.db
      - type: user_prompt
      # LSP for code intelligence
      - type: lsp
        command: gopls
        file_types: [".go"]
      # Custom scripts
      - type: script
        shell:
          run_tests:
            description: Run the test suite
            cmd: task test
          lint:
            description: Run the linter
            cmd: task lint
      # Custom API tool
      - type: api
        api_config:
          name: get_status
          method: GET
          endpoint: "https://api.example.com/status"
          instruction: Check service health
      # Docker MCP tools
      - type: mcp
        ref: docker:github-official
        tools: ["list_issues", "create_issue"]
      - type: mcp
        ref: docker:duckduckgo
      # Remote MCP
      - type: mcp
        remote:
          url: "https://internal-api.example.com/mcp"
          transport_type: "sse"
          headers:
            Authorization: "Bearer ${INTERNAL_TOKEN}"
```

--------------------------------

### Agent Configuration with LSP Tool

Source: https://github.com/docker/docker-agent/blob/main/docs/tools/lsp/index.md

Example agent configuration enabling LSP support for Go development.

```yaml
agents:
  developer:
    model: anthropic/claude-sonnet-4-5
    description: Code developer with LSP support
    instruction: You are a software developer.
    toolsets:
      - type: lsp
        command: gopls
        args: []
        file_types: [".go"]
      - type: filesystem
      - type: shell
```

--------------------------------

### Setup and Run LocalAI Server with Docker

Source: https://github.com/docker/docker-agent/blob/main/docs/providers/local/index.md

Run the LocalAI server using Docker, mapping a local directory for models. This command starts the server on port 8080.

```bash
# Run with Docker
docker run -p 8080:8080 --name local-ai \
  -v ./models:/models \
  localai/localai:latest-cpu
```

--------------------------------

### Build and Run docker-agent

Source: https://github.com/docker/docker-agent/blob/main/docs/community/contributing/index.md

Clone the repository, build the agent, set necessary API keys, and run an example configuration.

```bash
git clone https://github.com/docker/docker-agent.git
cd docker-agent
task build

# Set API keys
export OPENAI_API_KEY=your_key_here
export ANTHROPIC_API_KEY=your_key_here

# Run an example
./bin/docker-agent run examples/code.yaml
```

--------------------------------

### Combined MCP and Agent Configuration Example

Source: https://github.com/docker/docker-agent/blob/main/docs/tools/mcp/index.md

An example demonstrating a combined configuration for MCP servers and agents, including remote MCP definitions, toolset references, local stdio servers, and OAuth configurations.

```yaml
mcps:
  github:
    remote:
      url: https://api.githubcopilot.com/mcp
      transport_type: sse

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Full-featured developer assistant
    instruction: You are an expert developer.
    toolsets:
      # Docker MCP catalog entry
      - type: mcp
        ref: docker:duckduckgo

      # Reusable definition from the top-level mcps: block
      - type: mcp
        ref: github
        tools: ["list_issues", "create_issue"]
        toon: "list_.*"

      # Local stdio server with auto-install
      - type: mcp
        command: gopls
        version: "golang/tools@v0.21.0"
        args: ["mcp"]

      # Remote MCP with OAuth (handled automatically)
      - type: mcp
        remote:
          url: "https://mcp.linear.app/sse"
          transport_type: "sse"
        instruction: Use Linear for issue tracking.
```

--------------------------------

### Start docker-agent API Server

Source: https://github.com/docker/docker-agent/blob/main/AGENTS.md

Launches the API server for the docker-agent.

```bash
./bin/docker agent serve api
```

--------------------------------

### Start Chat Server with Multi-Agent Configuration

Source: https://github.com/docker/docker-agent/blob/main/docs/features/chat-server/index.md

Starts the chat server exposing multiple agents defined in a team.yaml configuration file. Each agent in the team becomes a selectable model.

```bash
# Multi-agent config — every agent in the team becomes a model
$ docker agent serve chat ./team.yaml
```

--------------------------------

### Start Chat Server with Agent from Registry

Source: https://github.com/docker/docker-agent/blob/main/docs/features/chat-server/index.md

Starts the chat server exposing an agent directly from a registry (agentcatalog/pirate) and specifies a custom listen address.

```bash
# Run an agent straight from the registry
$ docker agent serve chat agentcatalog/pirate --listen 127.0.0.1:9090
```

--------------------------------

### Start A2A Server Using Agent Catalog

Source: https://github.com/docker/docker-agent/blob/main/docs/features/a2a/index.md

Use this command to start an A2A server for an agent available in the agent catalog.

```bash
# Use an agent from the catalog
$ docker agent serve a2a agentcatalog/pirate
```

--------------------------------

### Start Chat Server with API Key Authentication

Source: https://github.com/docker/docker-agent/blob/main/docs/features/chat-server/index.md

Starts the chat server and requires a Bearer token for authentication, which is sourced from the CHAT_BEARER_TOKEN environment variable.

```bash
# Require a Bearer token, sourced from an env var
$ docker agent serve chat agent.yaml --api-key-env CHAT_BEARER_TOKEN
```

--------------------------------

### Enriching Toolset Instructions (Prepend)

Source: https://github.com/docker/docker-agent/blob/main/docs/configuration/tools/index.md

This example demonstrates prepending custom rules before the built-in instructions using the `{ORIGINAL_INSTRUCTIONS}` placeholder.

```yaml
toolsets:
  # Enrich: prepend your rules before the built-in instructions
  - type: shell
    instruction: |
      Important: only run commands inside the project root.
      {ORIGINAL_INSTRUCTIONS}
```

--------------------------------

### Start Chat Server and Select Specific Agent

Source: https://github.com/docker/docker-agent/blob/main/docs/features/chat-server/index.md

Starts the chat server with a multi-agent configuration but exposes only a specific agent named 'reviewer' as a model.

```bash
# Pick a specific agent from a multi-agent config
$ docker agent serve chat ./team.yaml --agent reviewer
```

--------------------------------

### Start Chat Server with Conversation Caching

Source: https://github.com/docker/docker-agent/blob/main/docs/features/chat-server/index.md

Starts the chat server with conversation caching enabled, allowing up to 100 conversations with a time-to-live of 30 minutes.

```bash
docker agent serve chat agent.yaml --conversations-max 100 --conversation-ttl 30m
```

--------------------------------

### Using Built-in Providers Inline

Source: https://github.com/docker/docker-agent/blob/main/docs/providers/overview/index.md

This example shows how to specify a built-in provider like Mistral directly in the agent configuration.

```bash
agents:
  root:
    model: mistral/mistral-large-latest
```

--------------------------------

### Download and Install docker-agent Binary (macOS/Linux)

Source: https://github.com/docker/docker-agent/blob/main/docs/getting-started/installation/index.md

Manually download, make executable, and install the docker-agent binary for macOS or Linux. This can be placed in the system's PATH or as a Docker CLI plugin.

```bash
# Download the latest release
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m); case "$ARCH" in x86_64) ARCH=amd64;; aarch64) ARCH=arm64;; esac
curl -L "https://github.com/docker/docker-agent/releases/latest/download/docker-agent-${OS}-${ARCH}" -o docker-agent
chmod +x docker-agent
sudo mv docker-agent /usr/local/bin/
docker-agent version

# or alternatively, instead of moving to /usr/local/bin:
mkdir -p ~/.docker/cli-plugins
sudo mv docker-agent ~/.docker/cli-plugins
docker agent version
```

--------------------------------

### Single MCP Server Integration

Source: https://github.com/docker/docker-agent/blob/main/pkg/creator/instructions.txt

Example of integrating a single MCP server, 'docker:youtube_transcript', into an agent's toolset.

```yaml
agents:
  root:
    toolsets:
      - type: mcp
        ref: docker:youtube_transcript
```

--------------------------------

### Docker Agent Configuration Example

Source: https://github.com/docker/docker-agent/blob/main/pkg/tui/components/markdown/testdata/streaming_benchmark.md

An example of the configuration file format for the Docker agent, written in YAML. It specifies settings for the server, database connection, and logging.

```yaml
server:
  host: localhost
  port: 8080
  timeout: 30s

database:
  driver: postgres
  connection: postgresql://user:pass@localhost/db
  pool_size: 10

logging:
  level: info
  format: json
  output: stdout
```

--------------------------------

### Auto Mode for Quick Start

Source: https://github.com/docker/docker-agent/blob/main/docs/guides/tips/index.md

Use 'auto' mode to let docker-agent automatically detect and use the best available API keys and models. This is useful for quick starts without a configuration file.

```bash
# Automatically uses the best available provider
$ docker agent run
```

--------------------------------

### Provider Shorthand Syntax Example

Source: https://github.com/docker/docker-agent/blob/main/docs/providers/custom/index.md

Illustrates using the shorthand 'provider_name/model' syntax for agents, which utilizes the provider's default settings.

```yaml
agents:
  root:
    model: my_gateway/gpt-4o-mini  # uses the provider's defaults
  researcher:
    model: my_anthropic/claude-sonnet-4-5  # uses anthropic provider defaults
```

--------------------------------

### Start Agent as A2A Server

Source: https://github.com/docker/docker-agent/blob/main/AGENTS.md

Initiates the agent as an A2A (Agent-to-Agent) server, configured with the provided YAML file.

```bash
./bin/docker agent serve a2a <config.yaml>
```

--------------------------------

### Filesystem Toolset Configuration

Source: https://github.com/docker/docker-agent/blob/main/docs/tools/filesystem/index.md

Basic configuration to enable the filesystem toolset. This is the minimal setup required to use the tool.

```yaml
toolsets:
  - type: filesystem
```

--------------------------------

### GET Request Example

Source: https://github.com/docker/docker-agent/blob/main/docs/tools/api/index.md

Example of configuring a GET request for the API tool, including endpoint interpolation and argument definitions.

```APIDOC
## GET search_users

### Description
Searches for users by name using a GET request.

### Method
GET

### Endpoint
https://api.example.com/users?q=${query}&limit=${limit}

### Parameters
#### Query Parameters
- **query** (string) - Required - Search query
- **limit** (integer) - Optional - Maximum results (default 10)

### Request Example
```yaml
toolsets:
  - type: api
    api_config:
      name: search_users
      method: GET
      endpoint: "https://api.example.com/users?q=${query}&limit=${limit}"
      instruction: Search for users by name
      args:
        query:
          type: string
          description: Search query
        limit:
          type: integer
          description: Maximum results (default 10)
      required: ["query"]
```
```

--------------------------------

### GitHub API Example: Get User

Source: https://github.com/docker/docker-agent/blob/main/docs/tools/api/index.md

Configuration for an agent to get information about a GitHub user using the GitHub API.

```yaml
toolsets:
  - type: api
    api_config:
      name: get_user
      method: GET
      endpoint: "https://api.github.com/users/${username}"
      instruction: Get information about a GitHub user
      args:
        username:
          type: string
          description: GitHub username
      required: ["username"]
      headers:
        Accept: "application/vnd.github.v3+json"
```

--------------------------------

### GitHub API Example: Get Repository

Source: https://github.com/docker/docker-agent/blob/main/docs/tools/api/index.md

Configuration for an agent to get information about a GitHub repository using the GitHub API.

```yaml
toolsets:
  - type: api
    api_config:
      name: get_repo
      method: GET
      endpoint: "https://api.github.com/repos/${owner}/${repo}"
      instruction: Get information about a GitHub repository
      args:
        owner:
          type: string
          description: Repository owner (user or org)
        repo:
          type: string
          description: Repository name
      required: ["owner", "repo"]
      headers:
        Accept: "application/vnd.github.v3+json"
        Authorization: "Bearer ${env.GITHUB_TOKEN}"
```

--------------------------------

### Initialize LLM Clients for Different Providers in Go

Source: https://github.com/docker/docker-agent/blob/main/docs/guides/go-sdk/index.md

Shows how to initialize clients for OpenAI, Anthropic, and Google Gemini providers with their respective model configurations.

```go
import (
    "github.com/docker/docker-agent/pkg/model/provider/anthropic"
    "github.com/docker/docker-agent/pkg/model/provider/gemini"
    "github.com/docker/docker-agent/pkg/model/provider/openai"
)

// OpenAI
openaiClient, _ := openai.NewClient(ctx, &latest.ModelConfig{
    Provider: "openai",
    Model:    "gpt-4o",
}, env)

// Anthropic
anthropicClient, _ := anthropic.NewClient(ctx, &latest.ModelConfig{
    Provider: "anthropic",
    Model:    "claude-sonnet-4-5",
}, env)

// Google Gemini
geminiClient, _ := gemini.NewClient(ctx, &latest.ModelConfig{
    Provider: "google",
    Model:    "gemini-2.5-flash",
}, env)
```

--------------------------------

### Session Start and End Hook Configuration

Source: https://github.com/docker/docker-agent/blob/main/docs/configuration/hooks/index.md

Configuration for session_start and session_end hooks. These hooks execute commands for environment setup at the start and cleanup at the end of a session, logging relevant information.

```yaml
hooks:
  session_start:
    - type: command
      timeout: 10
      command: |
        INPUT=$(cat)
        SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
        echo "Session $SESSION_ID started at $(date)" >> /tmp/agent-session.log
        echo '{"hook_specific_output":{"additional_context":"Session initialized."}}'

  session_end:
    - type: command
      timeout: 10
      command: |
        INPUT=$(cat)
        SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
        REASON=$(echo "$INPUT" | jq -r '.reason // "unknown"')
        echo "Session $SESSION_ID ended ($REASON) at $(date)" >> /tmp/agent-session.log
```

--------------------------------

### Example: Run Agent with Debugging and Custom Log File

Source: https://github.com/docker/docker-agent/blob/main/AGENTS.md

Demonstrates how to run the agent with debug logging enabled and a specific log file path.

```bash
./bin/docker-agent run config.yaml --debug --log-file ./debug.log
```

--------------------------------

### Get Docker Agent Version

Source: https://github.com/docker/docker-agent/blob/main/docs/features/cli/index.md

Retrieve the version and commit hash of your `docker-agent` installation using the `docker agent version` command.

```bash
$ docker agent version
docker agent version v1.54.0
Commit: 1737035c
```

--------------------------------

### Serve Web Content for Browser Demo

Source: https://github.com/docker/docker-agent/blob/main/cmd/wasm/README.md

Starts a simple HTTP server to serve the static files for the browser demo. This is required because WebAssembly streaming instantiation needs the correct MIME type, which `file://` URIs do not provide.

```sh
cd cmd/wasm/web && python3 -m http.server 8765
```

--------------------------------

### Example LSP Position Format

Source: https://github.com/docker/docker-agent/blob/main/docs/tools/lsp/index.md

Demonstrates the 1-based line and character position format used by all LSP tools. Ensure line and character numbers start from 1.

```json
{
  "file": "/path/to/file.go",
  "line": 42,
  "character": 15
}
```

--------------------------------

### Configure Agent Welcome Message

Source: https://github.com/docker/docker-agent/blob/main/docs/configuration/agents/index.md

Sets a custom welcome message to be displayed to users when a new agent session starts. This message can guide users on the agent's capabilities.

```yaml
agents:
  assistant:
    model: openai/gpt-5-mini
    description: Development assistant
    instruction: You are a helpful coding assistant.
    welcome_message: |
      👋 Welcome! I'm your development assistant.

      I can help you with:
      - Writing and reviewing code
      - Running tests and debugging
      - Explaining concepts

      What would you like to work on?
```

--------------------------------

### Docker Agent Code Assistant with Nebius

Source: https://github.com/docker/docker-agent/blob/main/docs/providers/nebius/index.md

Example of configuring a code assistant agent using a Nebius model. This setup includes filesystem, shell, and think toolsets for enhanced programming assistance.

```yaml
agents:
  coder:
    model: nebius/deepseek-ai/DeepSeek-V3
    description: Code assistant using DeepSeek
    instruction: |
      You are an expert programmer using DeepSeek V3.
      Write clean, well-documented code.
      Follow best practices for the language being used.
    toolsets:
      - type: filesystem
      - type: shell
      - type: think
```

--------------------------------

### Configure Session Options in Go

Source: https://github.com/docker/docker-agent/blob/main/docs/guides/go-sdk/index.md

Demonstrates how to create a new session with custom options, including setting a title, adding a user message, and limiting the number of iterations.

```go
import "github.com/docker/docker-agent/pkg/session"

sess := session.New(
    // Set a title for the session
    session.WithTitle("Code Review Task"),

    // Add user message
    session.WithUserMessage("Review this code for bugs"),

    // Limit iterations
    session.WithMaxIterations(20),
)
```

--------------------------------

### Install Docker Agent CLI

Source: https://github.com/docker/docker-agent/blob/main/pkg/tui/components/markdown/testdata/streaming_benchmark.md

Installs the Docker agent command-line interface using a shell script. Ensure you have curl and bash installed. This script fetches and executes the installation commands.

```bash
curl -fsSL https://example.com/install.sh | bash
```

--------------------------------

### Run a Pre-Built Agent from the Registry

Source: https://github.com/docker/docker-agent/blob/main/docs/getting-started/quickstart/index.md

Try a ready-made agent from the agent catalog without needing a YAML configuration file.

```bash
# Run a pirate-themed assistant
$ docker agent run agentcatalog/pirate
```

```bash
# Run a coding agent
$ docker agent run agentcatalog/coder
```

--------------------------------

### Verify Docker Agent Installation

Source: https://github.com/docker/docker-agent/blob/main/pkg/tui/components/markdown/testdata/streaming_benchmark.md

Verifies the successful installation of the Docker agent CLI by checking its version. This command should be run after the installation script completes.

```bash
docker agent version
```

--------------------------------

### Agent Run with Session Start Hook

Source: https://github.com/docker/docker-agent/blob/main/docs/features/cli/index.md

Execute a script when the agent session starts.

```bash
$ docker agent run agent.yaml --hook-session-start "./scripts/setup-env.sh"
```

--------------------------------

### Example Built-in Toolset Configuration

Source: https://github.com/docker/docker-agent/blob/main/docs/configuration/tools/index.md

This snippet shows how to configure a toolset with several built-in tools, including specifying a path for the memory tool.

```yaml
toolsets:
  - type: filesystem
  - type: shell
  - type: think
  - type: todo
  - type: memory
    path: ./dev.db
```

--------------------------------

### Defer Tools for Faster Startup

Source: https://github.com/docker/docker-agent/blob/main/docs/guides/tips/index.md

Improve agent startup performance by deferring the loading of large MCP toolsets until they are actually needed.

```yaml
agents:
  root:
    model: openai/gpt-4o
    description: Multi-tool assistant
    instruction: You have many tools available.
    toolsets:
      - type: mcp
        ref: docker:github-official
        defer: true
      - type: mcp
        ref: docker:slack
        defer: true
      - type: mcp
        ref: docker:linear
        defer: true
```

--------------------------------

### Install docker-agent with Homebrew

Source: https://github.com/docker/docker-agent/blob/main/docs/getting-started/installation/index.md

Install docker-agent using the Homebrew package manager on macOS or Linux.

```bash
# Install
$ brew install docker-agent

# Verify
$ docker-agent version
```

--------------------------------

### Start a Background Shell Job in a Custom Directory

Source: https://github.com/docker/docker-agent/blob/main/docs/tools/shell/index.md

Start a background job in a specified working directory.

```shell
run_background_job --cmd "ping google.com" --cwd "/var/log"
```

--------------------------------

### Configure Agent with Built-in Tools in Go

Source: https://github.com/docker/docker-agent/blob/main/docs/guides/go-sdk/index.md

Sets up an agent with various built-in tools, including shell, filesystem, think, and todo tools, along with runtime configuration.

```go
import (
    "github.com/docker/docker-agent/pkg/config"
    "github.com/docker/docker-agent/pkg/tools/builtin"
)

func createAgentWithBuiltinTools(llm provider.Provider) *agent.Agent {
    // Runtime config for tools that need it
    rtConfig := &config.RuntimeConfig{
        Config: config.Config{
            WorkingDir: "/path/to/workdir",
        },
    }

    return agent.New(
        "root",
        "You are a developer assistant.",
        agent.WithModel(llm),
        agent.WithToolSets(
            // Shell tool for running commands
            builtin.NewShellTool(os.Environ(), rtConfig),
            // Filesystem tools
            builtin.NewFilesystemTool(rtConfig.Config.WorkingDir),
            // Think tool for reasoning
            builtin.NewThinkTool(),
            // Todo tool for task tracking
            builtin.NewTodoTool(),
        ),
    )
}
```

--------------------------------

### Get User API (GitHub)

Source: https://github.com/docker/docker-agent/blob/main/docs/tools/api/index.md

This snippet demonstrates how to configure an API call to get information about a GitHub user. It requires the username.

```APIDOC
## GET /users/{username}

### Description
Retrieves information about a GitHub user.

### Method
GET

### Endpoint
https://api.github.com/users/${username}

### Parameters
#### Path Parameters
- **username** (string) - Required - GitHub username

### Headers
- **Accept**: "application/vnd.github.v3+json"
```

--------------------------------

### Start ACP Server on Stdio

Source: https://github.com/docker/docker-agent/blob/main/docs/features/acp/index.md

Use this command to start an ACP server that communicates over standard input/output. This is suitable for integrating with editors and IDEs.

```bash
# Start ACP server on stdio
$ docker agent serve acp ./agent.yaml
```

```bash
# With a multi-agent team config
$ docker agent serve acp ./team.yaml
```

```bash
# From the agent catalog
$ docker agent serve acp agentcatalog/pirate
```

```bash
# With a custom session database
$ docker agent serve acp ./agent.yaml --session-db ./my-sessions.db
```

--------------------------------

### Deferred Tool Loading (Entire Toolset)

Source: https://github.com/docker/docker-agent/blob/main/docs/configuration/tools/index.md

Defer the loading of entire toolsets to improve agent startup time. This example defers MCP toolsets for GitHub and Slack.

```yaml
toolsets:
  - type: mcp
    ref: docker:github-official
    defer: true
  - type: mcp
    ref: docker:slack
    defer: true
  - type: filesystem
```

--------------------------------

### Create Multi-Agent Teams in Go

Source: https://github.com/docker/docker-agent/blob/main/docs/guides/go-sdk/index.md

Demonstrates how to create a team of agents, including a root coordinator agent and a sub-agent (researcher), using the agent and team packages.

```go
package main

import (
    "github.com/docker/docker-agent/pkg/agent"
    "github.com/docker/docker-agent/pkg/team"
    "github.com/docker/docker-agent/pkg/tools/builtin"
)

func createTeam(llm provider.Provider) *team.Team {
    // Create a child agent
    researcher := agent.New(
        "researcher",
        "You research topics thoroughly.",
        agent.WithModel(llm),
        agent.WithDescription("Research specialist"),
    )

    // Create root agent with sub-agents
    coordinator := agent.New(
        "root",
        "You coordinate research tasks.",
        agent.WithModel(llm),
        agent.WithDescription("Team coordinator"),
        agent.WithSubAgents(researcher),
        agent.WithToolSets(builtin.NewTransferTaskTool()),
    )

    return team.New(team.WithAgents(coordinator, researcher))
}
```

--------------------------------

### Load Instructions from File

Source: https://github.com/docker/docker-agent/blob/main/examples/README.md

Demonstrates loading the system instruction from an external Markdown file using the `${file(...)}` syntax. Requires a separate instruction file.

```hcl
agent "instructions_from_file" {
  model = "gpt-4o"
  description = "Loads instruction from a file."
  instruction = "${file(./instructions_from_file.md)}"
}

```

--------------------------------

### Start Chat Server with Single Agent

Source: https://github.com/docker/docker-agent/blob/main/docs/features/chat-server/index.md

Starts the chat server exposing a single agent configured in agent.yaml. The agent will be available as the model 'root'.

```bash
# Single agent — exposed as the model `root`
$ docker agent serve chat agent.yaml
```

--------------------------------

### Configure Various Model Providers

Source: https://github.com/docker/docker-agent/blob/main/docs/configuration/models/index.md

Example configurations for different AI model providers including OpenAI, Anthropic, Google Gemini, AWS Bedrock, and Docker Model Runner.

```yaml
models:
  # OpenAI
  gpt:
    provider: openai
    model: gpt-5-mini

  # Anthropic
  claude:
    provider: anthropic
    model: claude-sonnet-4-5
    max_tokens: 64000

  # Google Gemini
  gemini:
    provider: google
    model: gemini-2.5-flash
    temperature: 0.5

  # AWS Bedrock
  bedrock:
    provider: amazon-bedrock
    model: global.anthropic.claude-sonnet-4-5-20250929-v1:0
    provider_opts:
      region: us-east-1

  # Docker Model Runner (local)
  local:
    provider: dmr
    model: ai/qwen3
    max_tokens: 8192
```

--------------------------------

### Example Eval Output

Source: https://github.com/docker/docker-agent/blob/main/examples/eval/README.md

This is an example of the output you can expect after running the Docker agent eval command. It shows the eval file identifiers and the calculated scores.

```text
Eval file: 41b179a2-ed19-4ae2-a45d-95775aaa90f7
Tool trajectory score: 1.000000
Rouge-1 score: 0.521739
Eval file: 5d83e247-061f-4462-9b2d-240facde45f3
Tool trajectory score: 1.000000
Rouge-1 score: 0.829268
```

--------------------------------

### Build Binary for Local Platform using Docker

Source: https://github.com/docker/docker-agent/blob/main/AGENTS.md

Builds the application binary for the local platform by leveraging Docker Buildx.

```bash
task build-local
```

--------------------------------

### Example SSE Stream Response

Source: https://github.com/docker/docker-agent/blob/main/docs/features/api-server/index.md

This shows an example of the Server-Sent Events (SSE) stream received from the agent. It includes lifecycle events and streamed content.

```bash
# Response (SSE stream):
data: {"type":"stream_started","session_id":"...","agent":"root"}
data: {"type":"agent_choice","content":"Hello! How","agent":"root"}
data: {"type":"agent_choice","content":" can I help","agent":"root"}
data: {"type":"agent_choice","content":" you today?","agent":"root"}
data: {"type":"stream_stopped","session_id":"...","agent":"root"}
```

--------------------------------

### Get Repository API

Source: https://github.com/docker/docker-agent/blob/main/docs/tools/api/index.md

This snippet shows how to configure an API call to get information about a specific GitHub repository. It requires the owner and repository name.

```APIDOC
## GET /repos/{owner}/{repo}

### Description
Retrieves information about a GitHub repository.

### Method
GET

### Endpoint
https://api.github.com/repos/${owner}/${repo}

### Parameters
#### Path Parameters
- **owner** (string) - Required - Repository owner (user or org)
- **repo** (string) - Required - Repository name

### Headers
- **Accept**: "application/vnd.github.v3+json"
- **Authorization**: "Bearer ${env.GITHUB_TOKEN}"
```

--------------------------------

### Go PostgreSQL Connection Pooling

Source: https://github.com/docker/docker-agent/blob/main/pkg/tui/components/markdown/testdata/streaming_benchmark.md

Demonstrates setting up a PostgreSQL database connection pool in Go using the standard library's database/sql package and the pq driver. It configures maximum connections, idle connections, and connection lifetimes.

```go
import (
	"database/sql"
	"time"

	_ "github.com/lib/pq"
)

func setupDatabase(connStr string) (*sql.DB, error) {
	db, err := sql.Open("postgres", connStr)
	if err != nil {
		return nil, err
	}

	db.SetMaxOpenConns(25)
	db.SetMaxIdleConns(5)
	db.SetConnMaxLifetime(5 * time.Minute)
	db.SetConnMaxIdleTime(1 * time.Minute)

	if err := db.Ping(); err != nil {
		return nil, err
	}

	return db, nil
}
```

--------------------------------

### Example Docker Agent YAML Configuration

Source: https://github.com/docker/docker-agent/blob/main/cmd/wasm/README.md

Demonstrates a YAML configuration for the docker-agent, specifying an LLM provider (OpenRouter) and an agent model.

```yaml
providers:
  openrouter:
    provider: openai
    base_url: https://openrouter.ai/api/v1
    token_key: OPENROUTER_API_KEY
agents:
  root:
    model: openrouter/meta-llama/llama-3.3-70b-instruct:free
    instruction: |
      You are a helpful assistant ...

```

--------------------------------

### GET Request with URL Parameters

Source: https://github.com/docker/docker-agent/blob/main/docs/tools/api/index.md

Define a GET request tool that interpolates query parameters directly into the URL. This is useful for search or filtering operations.

```yaml
toolsets:
  - type: api
    api_config:
      name: search_users
      method: GET
      endpoint: "https://api.example.com/users?q=${query}&limit=${limit}"
      instruction: Search for users by name
      args:
        query:
          type: string
          description: Search query
        limit:
          type: integer
          description: Maximum results (default 10)
      required: ["query"]
```

--------------------------------

### Anthropic Team Setup

Source: https://github.com/docker/docker-agent/blob/main/docs/providers/custom/index.md

Configure access to Anthropic models using a team API key. This setup allows for specific model and budget configurations.

```yaml
providers:
  team_anthropic:
    provider: anthropic
    token_key: TEAM_ANTHROPIC_KEY
    max_tokens: 32768
    thinking_budget: high
    temperature: 0.5

models:
  architect:
    provider: team_anthropic
    model: claude-sonnet-4-5

  reviewer:
    provider: team_anthropic
    model: claude-haiku-4-5
    thinking_budget: low  # faster reviews

agents:
  root:
    model: architect
    sub_agents: [code_reviewer]
  code_reviewer:
    model: reviewer
```

--------------------------------

### Configuring Multiple AI Model Providers

Source: https://github.com/docker/docker-agent/blob/main/docs/providers/overview/index.md

This example demonstrates how to configure different AI model providers for various agents within the same configuration file. It shows how to assign specific models and providers like Anthropic, OpenAI, and Docker Model Runner to different agents, enabling cost optimization and task-specific model selection.

```yaml
models:
  claude:
    provider: anthropic
    model: claude-sonnet-4.5
    max_tokens: 64000
  gpt:
    provider: openai
    model: gpt-5-mini
  local:
    provider: dmr
    model: ai/qwen3
agents:
  root:
    model: claude # coordinator uses Claude
    sub_agents: [coder, helper]
  coder:
    model: gpt # coder uses GPT-5-mini
  helper:
    model: local # helper runs locally for free
```

--------------------------------

### Run Dogfooding Agent

Source: https://github.com/docker/docker-agent/blob/main/docs/community/contributing/index.md

Navigate to the project directory and run the specialized Go developer agent using its configuration file.

```bash
cd docker-agent
docker agent run ./golang_developer.yaml
```

--------------------------------

### Disable Auto-Install for a Specific Toolset

Source: https://github.com/docker/docker-agent/blob/main/docs/configuration/tools/index.md

To disable automatic installation for a particular toolset, set the 'version' property to 'false' or 'off'. This prevents the agent from attempting to download and install the command binary.

```yaml
toolsets:
  - type: mcp
    command: my-custom-server
    version: "false"
```

--------------------------------

### Create Skill Directory and SKILL.md

Source: https://github.com/docker/docker-agent/blob/main/docs/features/skills/index.md

This snippet shows how to create the necessary directory structure and the SKILL.md file for a new skill. The SKILL.md file defines the skill's name, description, and behavior.

```bash
# Create the skill directory
$ mkdir -p ~/.agents/skills/create-dockerfile

# Write the SKILL.md file
$ cat > ~/.agents/skills/create-dockerfile/SKILL.md << 'EOF'
---
name: create-dockerfile
description: Create optimized Dockerfiles for applications
---

# Creating Dockerfiles

When asked to create a Dockerfile:

1. Analyze the application type and language
2. Use multi-stage builds for compiled languages
3. Use slim base images to minimize size
4. Run as non-root user for security
EOF
```

--------------------------------

### Quick Start Configuration for RAG Tool

Source: https://github.com/docker/docker-agent/blob/main/docs/tools/rag/index.md

Configure a RAG knowledge base named 'my_docs' with a description and specify document paths. Assign this knowledge base to an agent using 'type: rag' and 'ref: my_docs'.

```yaml
rag:
  my_docs:
    tool:
      description: "Technical documentation"
    docs: [./documents, ./some-doc.md]
    strategies:
      - type: chunked-embeddings
        embedding_model: openai/text-embedding-3-small
        database: ./docs.db
        vector_dimensions: 1536

agents:
  root:
    model: openai/gpt-4o
    instruction: |
      You have access to a knowledge base. Use it to answer questions.
    toolsets:
      - type: rag
        ref: my_docs
```