Português
Documentação
Agentes

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 nenhuma alteração 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 percorrê-los 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 três subagentes integrados, General, Explore e Scout. Vamos ver esses abaixo.

Integrados

O OpenCode vem com dois agentes primários integrados e três 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 arquivo 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 a você e prevenir alterações não intencionais. Por padrão, todos os seguintes estão definidos 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 nenhuma modificação real 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 scout

Modo: subagent

Um agente somente leitura para documentação externa e pesquisa de dependências. Use quando precisar clonar o repositório de uma dependência no cache gerenciado pelo OpenCode, inspecionar o código-fonte de uma biblioteca ou cruzar o código local com implementações upstream sem modificar seu workspace.

Usar compaction

Modo: primary

Agente do sistema oculto que compacta um 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

  1. Para agentes primários, use a tecla Tab para percorrê-los durante uma sessão. Você também pode usar sua combinação de teclas switch_agent configurada.

  2. Subagentes podem ser invocados:

    • Automaticamente por agentes primários para tarefas especializadas com base em suas descrições.

    • Manualmente mencionando com @ um subagente na sua mensagem. Por exemplo.

      @general help me search for this function

  3. Navegação entre sessões: Quando subagentes criam sessões filhas, use session_child_first (padrão: <Leader>+Down) para entrar na primeira sessão filha a partir da pai.

  4. Uma vez dentro de uma sessão filha, use:

    • session_child_cycle (padrão: Right ) para avançar para a próxima sessão filha
    • session_child_cycle_reverse (padrão: Left ) para retroceder para a sessão filha anterior
    • session_parent (padrão: Up ) para retornar à sessão pai

    Isso permite alternar 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 config 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}",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "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.",
      "permission": {
        "edit": "deny"
      }
    }
  }
}

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
permission:
  edit: deny
  bash: deny
---
 
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 config obrigatória.

Temperature

Controle a aleatoriedade e criatividade das respostas do LLM com a config temperature.

Valores mais baixos tornam as respostas mais focadas e determinísticas, enquanto valores mais altos aumentam a criatividade e a 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 config 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 config está localizado. Então isso funciona tanto para a config global do OpenCode quanto para a config específica do projeto.

Model

Use a config model para substituir o modelo deste 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 config do OpenCode usa o formato provider/model-id. Por exemplo, se você está usando o OpenCode Zen, você usaria opencode/gpt-5.1-codex para o GPT 5.1 Codex.

Tools (obsoleto)

tools está obsoleto. Prefira o campo permission do agente para novas configs, atualizações e controle mais granular.

Permite controlar quais ferramentas estão disponíveis neste agente. Você pode habilitar ou desabilitar ferramentas específicas definindo-as como true ou false. Na config tools de um agente, true é equivalente à permissão {"*": "allow"} e false é equivalente à permissão {"*": "deny"}.

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

Nota: A config específica do agente substitui a config global.

Você também pode usar curingas em entradas legadas de tools 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. Cada chave de permissão pode ser definida como:

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

As chaves de permissão disponíveis são:

ChaveFerramentas que ela controla
readread
editwrite, edit, apply_patch
globglob
grepgrep
listlist
bashbash
tasktask
external_directoryQualquer ferramenta que lê ou escreve arquivos fora do worktree do projeto
todowritetodowrite, todoread
webfetchwebfetch
websearchwebsearch
lsplsp
skillskill
questionquestion
doom_loopPrompts de recuperação quando um agente parece travado

read, edit, glob, grep, list, bash, task, external_directory, lsp e skill aceitam tanto uma ação abreviada ("allow" | "ask" | "deny") quanto um objeto de glob/padrão → ação para controle granular. As chaves restantes aceitam apenas a ação abreviada.

Nota: As chaves de permissão são correspondidas como padrões curinga contra o nome da ferramenta subjacente, então a mesma sintaxe funciona para ferramentas integradas, ferramentas personalizadas e ferramentas MCP — por exemplo, "mymcp_*": "deny" nega todas as ferramentas de um servidor MCP, e "mymcp_search": "ask" mira em apenas uma.

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 de todos os comandos. Como a última regra correspondente tem precedência, coloque o curinga * primeiro e as 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 config 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 para o 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: As 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 o 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 uma cor de tema: primary, secondary, accent, success, warning, error, info.

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

Top P

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

opencode.json
{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

Os 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 do provedor. Verifique a documentação do seu provedor para os 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á:

  1. Perguntar onde salvar o agente; global ou específico do projeto.
  2. Descrição do que o agente deve fazer.
  3. Gerar um prompt do sistema e identificador apropriados.
  4. Permitir que você selecione quais permissões o agente pode ter (qualquer coisa que você não selecionar é negada).
  5. 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 read habilitadas
  • Agente Docs : Escrita de documentação com operações de arquivo, 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
permission:
  bash: deny
---
 
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
permission:
  edit: deny
---
 
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
RegrasModelos