Agentes

Configure e use agentes especializados.

Agentes são assistentes de IA especializados que podem ser configurados para tarefas e fluxos de trabalho específicos. Eles permitem criar ferramentas focadas com prompts personalizados, modelos e acesso a ferramentas.

Dica: Use o agente plan para analisar código e revisar sugestões sem fazer alterações no código.

Você pode alternar entre agentes durante uma sessão ou invocá-los com a menção @.

Tipos

Existem dois tipos de agentes no OpenCode: agentes primários e subagentes.

Agentes primários

Agentes primários são os assistentes principais com os quais você interage diretamente. Você pode alternar entre eles usando a tecla Tab ou sua combinação de teclas switch_agent configurada. Esses agentes lidam com sua conversa principal. O acesso a ferramentas é configurado via permissões — por exemplo, Build tem todas as ferramentas habilitadas enquanto Plan é restrito.

Dica: Você pode usar a tecla Tab para alternar entre agentes primários durante uma sessão.

O OpenCode vem com dois agentes primários integrados: Build e Plan. Vamos ver esses abaixo.

Subagentes

Subagentes são assistentes especializados que agentes primários podem invocar para tarefas específicas. Você também pode invocá-los manualmente mencionando com @ em suas mensagens.

O OpenCode vem com dois subagentes integrados: General e Explore. Vamos ver esses abaixo.

Integrados

O OpenCode vem com dois agentes primários integrados e dois subagentes integrados.

Usar build

Modo: primary

Build é o agente primário padrão com todas as ferramentas habilitadas. Este é o agente padrão para trabalho de desenvolvimento onde você precisa de acesso completo a operações de arquivos e comandos do sistema.

Usar plan

Modo: primary

Um agente restrito projetado para planejamento e análise. Usamos um sistema de permissões para dar mais controle e prevenir alterações não intencionais. Por padrão, todos os seguintes estão configurados como ask:

file edits: Todas as escritas, patches e edições
bash: Todos os comandos bash

Este agente é útil quando você quer que o LLM analise código, sugira alterações ou crie planos sem fazer modificações reais na sua base de código.

Usar general

Modo: subagent

Um agente de propósito geral para pesquisar questões complexas e executar tarefas de múltiplas etapas. Tem acesso completo a ferramentas (exceto todo), então pode fazer alterações em arquivos quando necessário. Use para executar múltiplas unidades de trabalho em paralelo.

Usar explore

Modo: subagent

Um agente rápido somente leitura para explorar bases de código. Não pode modificar arquivos. Use quando precisar encontrar arquivos rapidamente por padrões, buscar palavras-chave no código ou responder perguntas sobre a base de código.

Usar compaction

Modo: primary

Agente do sistema oculto que compacta contexto longo em um resumo menor. Executa automaticamente quando necessário e não é selecionável na interface.

Usar title

Modo: primary

Agente do sistema oculto que gera títulos curtos de sessão. Executa automaticamente e não é selecionável na interface.

Usar summary

Modo: primary

Agente do sistema oculto que cria resumos de sessão. Executa automaticamente e não é selecionável na interface.

Uso

Para agentes primários, use a tecla Tab para alternar entre eles durante uma sessão. Você também pode usar sua combinação de teclas switch_agent configurada.
Subagentes podem ser invocados:
- Automaticamente por agentes primários para tarefas especializadas baseadas em suas descrições.
- Manualmente mencionando com @ um subagente na sua mensagem. Por exemplo:
```
@general help me search for this function
```
Navegação entre sessões: Quando subagentes criam suas próprias sessões filhas, você pode navegar entre a sessão pai e todas as sessões filhas usando:
- <Leader>+Right (ou sua combinação session_child_cycle configurada) para avançar: pai → filho1 → filho2 → … → pai
- <Leader>+Left (ou sua combinação session_child_cycle_reverse configurada) para retroceder: pai ← filho1 ← filho2 ← … ← pai
Isso permite alternar perfeitamente entre a conversa principal e o trabalho especializado do subagente.

Configurar

Você pode personalizar os agentes integrados ou criar os seus próprios através de configuração. Agentes podem ser configurados de duas maneiras:

JSON

Configure agentes no seu arquivo de configuração opencode.json:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

Você também pode definir agentes usando arquivos markdown. Coloque-os em:

Global: ~/.config/opencode/agents/
Por projeto: .opencode/agents/

~/.config/opencode/agents/review.md

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---
 
You are in code review mode. Focus on:
 
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations
 
Provide constructive feedback without making direct changes.

O nome do arquivo markdown se torna o nome do agente. Por exemplo, review.md cria um agente review.

Opções

Vamos ver essas opções de configuração em detalhes.

Description

Use a opção description para fornecer uma breve descrição do que o agente faz e quando usá-lo.

opencode.json

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

Esta é uma opção de configuração obrigatória.

Temperature

Controle a aleatoriedade e criatividade das respostas do LLM com a configuração temperature.

Valores mais baixos tornam as respostas mais focadas e determinísticas, enquanto valores mais altos aumentam a criatividade e variabilidade.

opencode.json

{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Valores de temperature tipicamente variam de 0.0 a 1.0:

0.0-0.2: Respostas muito focadas e determinísticas, ideais para análise de código e planejamento
0.3-0.5: Respostas equilibradas com alguma criatividade, boas para tarefas de desenvolvimento geral
0.6-1.0: Respostas mais criativas e variadas, úteis para brainstorming e exploração

opencode.json

{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

Se nenhuma temperature for especificada, o OpenCode usa padrões específicos do modelo; tipicamente 0 para a maioria dos modelos, 0.55 para modelos Qwen.

Max steps

Controle o número máximo de iterações agênticas que um agente pode realizar antes de ser forçado a responder apenas com texto. Isso permite que usuários que desejam controlar custos definam um limite nas ações agênticas.

Se não for definido, o agente continuará iterando até que o modelo escolha parar ou o usuário interrompa a sessão.

opencode.json

{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

Quando o limite é atingido, o agente recebe um prompt do sistema especial instruindo-o a responder com um resumo do seu trabalho e tarefas restantes recomendadas.

Cuidado: O campo legado maxSteps está obsoleto. Use steps em vez disso.

Disable

Defina como true para desabilitar o agente.

opencode.json

{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

Especifique um arquivo de prompt do sistema personalizado para este agente com a configuração prompt. O arquivo de prompt deve conter instruções específicas para o propósito do agente.

opencode.json

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

Este caminho é relativo a onde o arquivo de configuração está localizado. Então isso funciona tanto para a configuração global do OpenCode quanto para a configuração específica do projeto.

Model

Use a configuração model para substituir o modelo para este agente. Útil para usar diferentes modelos otimizados para diferentes tarefas. Por exemplo, um modelo mais rápido para planejamento, um modelo mais capaz para implementação.

Dica: Se você não especificar um modelo, agentes primários usam o modelo configurado globalmente enquanto subagentes usarão o modelo do agente primário que invocou o subagente.

opencode.json

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

O ID do modelo na sua configuração do OpenCode usa o formato provider/model-id. Por exemplo, se você está usando OpenCode Zen, você usaria opencode/gpt-5.1-codex para GPT 5.1 Codex.

Tools

Controle quais ferramentas estão disponíveis neste agente com a configuração tools. Você pode habilitar ou desabilitar ferramentas específicas definindo-as como true ou false.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

Nota: A configuração específica do agente substitui a configuração global.

Você também pode usar curingas para controlar múltiplas ferramentas de uma vez. Por exemplo, para desabilitar todas as ferramentas de um servidor MCP:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

Saiba mais sobre ferramentas.

Permissions

Você pode configurar permissões para gerenciar quais ações um agente pode tomar. Atualmente, as permissões para as ferramentas edit, bash e webfetch podem ser configuradas como:

"ask" — Solicitar aprovação antes de executar a ferramenta
"allow" — Permitir todas as operações sem aprovação
"deny" — Desabilitar a ferramenta

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

Você pode substituir essas permissões por agente.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

Você também pode definir permissões em agentes Markdown.

~/.config/opencode/agents/review.md

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---
 
Only analyze code and suggest changes.

Você pode definir permissões para comandos bash específicos.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

Isso pode usar um padrão glob.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

E você também pode usar o curinga * para gerenciar permissões para todos os comandos. Como a última regra correspondente tem precedência, coloque o curinga * primeiro e regras específicas depois.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

Saiba mais sobre permissões.

Mode

Controle o modo do agente com a configuração mode. A opção mode é usada para determinar como o agente pode ser usado.

opencode.json

{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

A opção mode pode ser definida como primary, subagent ou all. Se nenhum mode for especificado, o padrão é all.

Hidden

Oculte um subagente do menu de autocompletar @ com hidden: true. Útil para subagentes internos que devem ser invocados apenas programaticamente por outros agentes através da ferramenta Task.

opencode.json

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

Isso afeta apenas a visibilidade do usuário no menu de autocompletar. Agentes ocultos ainda podem ser invocados pelo modelo através da ferramenta Task se as permissões permitirem.

Nota: Aplica-se apenas a agentes com mode: subagent.

Task permissions

Controle quais subagentes um agente pode invocar através da ferramenta Task com permission.task. Usa padrões glob para correspondência flexível.

opencode.json

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

Quando definido como deny, o subagente é removido completamente da descrição da ferramenta Task, então o modelo não tentará invocá-lo.

Dica: Regras são avaliadas em ordem, e a última regra correspondente vence. No exemplo acima, orchestrator-planner corresponde tanto a * (deny) quanto a orchestrator-* (allow), mas como orchestrator-* vem depois de *, o resultado é allow.

Dica: Usuários sempre podem invocar qualquer subagente diretamente através do menu de autocompletar @, mesmo se as permissões de tarefa do agente negariam.

Color

Personalize a aparência visual do agente na interface com a opção color. Isso afeta como o agente aparece na interface.

Use uma cor hexadecimal válida (ex. #FF5733) ou cor do tema: primary, secondary, accent, success, warning, error, info.

opencode.json

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

Top P

Controle a diversidade de respostas com a opção top_p. Alternativa a temperature para controlar aleatoriedade.

opencode.json

{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

Valores variam de 0.0 a 1.0. Valores mais baixos são mais focados, valores mais altos mais diversos.

Additional

Quaisquer outras opções que você especificar na sua configuração de agente serão passadas diretamente para o provedor como opções do modelo. Isso permite usar recursos e parâmetros específicos do provedor.

Por exemplo, com os modelos de raciocínio da OpenAI, você pode controlar o esforço de raciocínio:

opencode.json

{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

Essas opções adicionais são específicas do modelo e provedor. Verifique a documentação do seu provedor para parâmetros disponíveis.

Dica: Execute opencode models para ver uma lista dos modelos disponíveis.

Criar agentes

Você pode criar novos agentes usando o seguinte comando:

opencode agent create

Este comando interativo irá:

Perguntar onde salvar o agente: global ou específico do projeto.
Descrição do que o agente deve fazer.
Gerar um prompt do sistema e identificador apropriados.
Permitir selecionar quais ferramentas o agente pode acessar.
Finalmente, criar um arquivo markdown com a configuração do agente.

Casos de uso

Aqui estão alguns casos de uso comuns para diferentes agentes.

Agente Build: Trabalho de desenvolvimento completo com todas as ferramentas habilitadas
Agente Plan: Análise e planejamento sem fazer alterações
Agente Review: Revisão de código com acesso somente leitura mais ferramentas de documentação
Agente Debug: Focado em investigação com ferramentas bash e leitura habilitadas
Agente Docs: Escrita de documentação com operações de arquivos mas sem comandos do sistema

Exemplos

Aqui estão alguns agentes de exemplo que você pode achar úteis.

Dica: Tem um agente que gostaria de compartilhar? Envie um PR (opens in a new tab).

Agente de documentação

~/.config/opencode/agents/docs-writer.md

---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---
 
You are a technical writer. Create clear, comprehensive documentation.
 
Focus on:
 
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Auditor de segurança

~/.config/opencode/agents/security-auditor.md

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---
 
You are a security expert. Focus on identifying potential security issues.
 
Look for:
 
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

Regras Modelos