DEV Community

Cover image for Docker Compose para Agentes de IA: O que realmente mudou (e o que você precisa saber agora)
Rafael Pazini
Rafael Pazini

Posted on

Docker Compose para Agentes de IA: O que realmente mudou (e o que você precisa saber agora)

#docker #ai #development #agents

Se você acompanha o ecossistema Docker, 2025 foi o ano em que eles deixaram de ser "só a ferramenta de containerização" e viraram plataforma de IA de verdade. E o que começou como experimento virou padrão com uma velocidade impressionante — tipo aquele colega que vai a uma conferência e volta querendo reescrever tudo em Rust.

O ponto central de tudo isso é simples: modelos de IA agora são cidadãos de primeira classe no seu compose.yaml. Mesma sintaxe, mesma CLI, mesmo pipeline que você já usa para subir Postgres e Redis. A diferença é que agora o Qwen ou o Gemma também sobem junto.

Vamos ver o que realmente funciona em fevereiro de 2026 e o que você deveria estar usando.

O que mudou no Compose

O artigo de referência estava certo no espírito, mas a sintaxe evoluiu. O bloco provider.type: model com imagens Docker Hub genéricas não é a forma atual. Isso foi simplificado.

A sintaxe correta hoje usa o campo model dentro do bloco models para referenciar o artefato OCI direto do Docker Hub, sem a estrutura aninhada de provider:

models:
  llm:
    model: ai/qwen2.5        # artefato OCI do Docker Hub — isso que você puxa
    context_size: 4096
  embeddings:
    model: ai/all-minilm
    context_size: 2048
    runtime_flags:
      - "--embeddings"       # obrigatório para modelos de embedding

services:
  api:
    build: ./api
    models:
      llm:
        endpoint_var: LLM_URL       # Compose injeta a URL do Model Runner aqui
        model_var: LLM_MODEL_NAME
      embeddings:
        endpoint_var: EMBEDDING_URL
        model_var: EMBEDDING_MODEL_NAME

  vector-db:
    image: qdrant/qdrant:latest
    volumes:
      - ./qdrant:/qdrant/storage
Enter fullscreen mode Exit fullscreen mode

Depois é só:

docker compose up
Enter fullscreen mode Exit fullscreen mode

O Compose puxa os modelos do Docker Hub, sobe o Model Runner, injeta as variáveis de ambiente nos serviços que precisam, e cuida da ordem de inicialização. Você não escreve nenhuma linha de código de infraestrutura.

Versão mínima: Docker Compose 2.38.1+. Se você roda no Linux com Docker Engine (não Desktop), confirme a versão antes. Se roda Docker Desktop, já está coberto.

O ecossistema expandiu bastante

Quando esse assunto surgiu em julho de 2025, os frameworks suportados eram CrewAI, LangGraph e Spring AI. Hoje a lista ficou bem maior. Oficialmente, o repo docker/compose-for-agents tem exemplos funcionando para:

  • LangGraph (Python)
  • CrewAI (Python)
  • Spring AI (Java)
  • Embabel (JVM)
  • Vercel AI SDK (Node.js)
  • Google ADK — esse é novo e é o mais interessante para quem trabalha com raciocínio multi-step

Para Go, o caminho natural ainda é via Langchaingo ou chamadas HTTP diretas — o Compose injeta a URL, o resto é o seu código.

Gordon: o agente que o Docker não estava avisando que ia lançar

Se você não acompanhou, em fevereiro de 2026 o Docker lançou o Gordon — um agente de IA dentro do Docker Desktop (e CLI via docker ai) que tem acesso ao seu ambiente de containers.

O Gordon não é um chatbot. Ele tem shell, CLI do Docker e acesso ao filesystem. Você aponta um problema, aprova as ações, e ele executa. Container saindo com código 137? Gordon inspeciona os logs, identifica o processo que estourou memória, propõe o fix. Você aprova, ele executa.

docker ai "meu container de API está caindo, me ajuda a debugar"
Enter fullscreen mode Exit fullscreen mode

Vale mencionar porque afeta diretamente o fluxo de trabalhar com agentes: o Gordon é construído em cima do cagent, o framework de agentes do Docker, e se integra diretamente com o MCP Gateway. Ou seja, a mesma arquitetura que você define no Compose para seus agentes, o Docker está usando internamente.

Nota de segurança: Em fevereiro de 2026 foi divulgada uma vulnerabilidade onde labels maliciosas em imagens Docker podiam ser usadas para injetar comandos via Gordon → MCP Gateway. Isso foi corrigido na versão 4.50.0+. Se você está em versão anterior, atualize antes de usar Gordon em projetos com imagens de terceiros.

MCP Gateway e MCP Catalog: o que isso muda na prática

Outro componente que o artigo original mencionava de forma superficial e que ficou muito mais relevante: o MCP Gateway, agora open source e GA desde a versão 4.43 do Desktop.

O Gateway é o ponto de controle entre seus agentes e as ferramentas externas. Ele fica no meio do caminho entre o agente (seja LangGraph, CrewAI, ou o próprio Gordon) e os MCP servers (ferramentas como GitHub, MongoDB, Slack, banco de dados, etc.).

No Compose, a integração fica assim:

services:
  my-agent:
    build: ./agent
    models:
      llm:
        endpoint_var: LLM_URL
        model_var: LLM_MODEL_NAME
    environment:
      MCP_GATEWAY_URL: http://mcp-gateway:8811
    depends_on:
      - mcp-gateway
      - llm

  mcp-gateway:
    image: docker/mcp-gateway:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - MCP_SERVERS=github,duckduckgo

models:
  llm:
    model: ai/qwen2.5
Enter fullscreen mode Exit fullscreen mode

O MCP Catalog hoje tem mais de 100 servidores verificados, todos rodando em containers isolados com assinatura criptográfica — muito diferente do padrão anterior de executar via npx ou uvx direto no host.

Model Runner: o que evoluiu desde o lançamento

O Docker Model Runner (DMR) saiu de beta experimental para GA em outubro de 2025. Desde então:

  • Suporte a Windows com GPU NVIDIA e Qualcomm/ARM
  • API compatível com OpenAI (você troca o endpoint, o SDK não muda)
  • API compatível com Anthropic — adicionada recentemente, para quem usa SDKs do Claude
  • docker model purge para limpar todos os modelos de uma vez
  • Você pode omitir o prefixo ai/ ao fazer pull: docker model pull qwen2.5 funciona
  • Downloads retomam se interrompidos — acabou aquela dor de baixar modelos de 4GB na metade 
# Antes
docker model pull ai/qwen2.5

# Agora funciona igual
docker model pull qwen2.5

# Endpoint OpenAI-compatible (sem o /engines agora)
curl http://localhost:12434/v1/models
Enter fullscreen mode Exit fullscreen mode

Docker Compose v5 e o Go SDK

Isso ainda não estava no radar quando o artigo original foi escrito: o Compose v5 saiu com um SDK Go oficial que permite controle programático do ambiente multi-container sem depender da CLI.

Para quem escreve ferramentas de plataforma ou pipelines de CI em Go, isso é relevante. Você pode validar, carregar e gerenciar ambientes Compose diretamente no seu código:

import "github.com/compose-spec/compose-go/v2/cli"

// Carrega e valida o compose.yaml programaticamente
options, _ := cli.NewProjectOptions([]string{"compose.yaml"})
project, _ := options.LoadProject(context.Background())

// Valida que os modelos declarados existem no hub
for name, model := range project.Models {
    fmt.Printf("Model: %s → %s\n", name, model.Model)
}
Enter fullscreen mode Exit fullscreen mode

Cloud Run e o que está por vir

O deploy para Google Cloud Run via gcloud run compose up é real e funcional. Azure está em andamento. AWS ainda não tem integração oficial — e analistas apontaram isso como um gap relevante para adoção enterprise.

A limitação prática: Offload funciona bem para desenvolvimento e testes pesados. Para produção com autoscaling multi-região gerenciado fora do Docker, você ainda precisa de outras peças.

Boas práticas que o tempo confirmou

Algumas coisas que a comunidade aprendeu na prática desde o lançamento:

Versione seus modelos com digest, não tag. A tag latest do modelo pode mudar semanticamente sem aviso. Se seu agente começou a dar respostas diferentes sem você ter mudado nada, a culpa pode ser essa.

models:
  llm:
    model: ai/qwen2.5@sha256:abc123... # imutável
Enter fullscreen mode Exit fullscreen mode

Separe embedding do modelo principal. Colocar os dois no mesmo serviço aumenta latência de forma desnecessária. São padrões de uso completamente diferentes.

Use variáveis mapeadas via sintaxe longa. Desacopla o nome lógico interno dos detalhes do endpoint e facilita a troca entre local e Offload sem refatorar código.

Valide no CI. O Compose trata modelos como qualquer serviço, então você pode subir a stack headless e rodar smoke tests contra o endpoint do modelo:

# CI pipeline
docker compose up -d
sleep 10  # aguarda modelo carregar
curl -f http://localhost:12434/v1/models || exit 1
docker compose down
Enter fullscreen mode Exit fullscreen mode

Quando usar (e quando esperar)

Use agora se você precisa de: desenvolvimento full-stack local consistente com LLM, CI previsível que testa inferência como dependência normal, múltiplos agentes se comunicando sem scripts manuais, ou uma stack RAG com vector store e modelo local.

Espere se você precisa de: autoscaling multi-região fora do ecossistema Docker (ainda imaturo), integrações com plataformas ML proprietárias que não publicam artefato OCI, ou AWS como provedor cloud principal para o Compose (sem suporte oficial ainda).

O ponto central

No momento atual, a pergunta não é mais "vale a pena testar?" — é "por qual parte você começa?"

A resposta mais simples: clone o docker/compose-for-agents, escolha o exemplo do framework que seu time já usa (LangGraph se você é Python, Spring AI se é Java, vai de Go direto via HTTP), suba com docker compose up, e meça quanto tempo você economizou não configurando nada.

Depois me conta.

Dúvidas ou ajustes? Abre uma issue no meu repositório de artigos. E se você já está rodando Compose com modelos em produção, me conta como está sendo — esse tema ainda tem muita coisa para explorar.

Top comments (0)