Pular para o conteúdo
OpenCode
app.header.homeapp.header.docs

Agentes

Configure e use agentes especializados.

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

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 principais assistentes com os quais você interage diretamente. Você pode alternar entre eles usando a tecla Tab ou sua tecla de atalho configurada switch_agent. Esses agentes lidam com sua conversa principal. O acesso às ferramentas é configurado por meio de permissões — por exemplo, Build tem todas as ferramentas habilitadas, enquanto Plan é restrito.

opencode vem com dois agentes primários integrados, Build e Plan. Vamos ver isso 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-os com @ em suas mensagens.

opencode vem com dois subagentes integrados, General e Explore. Vamos ver isso abaixo.

Integrado

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 total 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 lhe dar mais controle e evitar alterações não intencionais. Por padrão, todos os seguintes estão configurados para ask:

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

Este agente é útil quando você deseja que o LLM analise código, sugira alterações ou crie planos sem fazer modificações reais em seu código.

Usar general

Modo: subagent

Um agente de propósito geral para pesquisar questões complexas e executar tarefas em múltiplas etapas. Tem acesso total às ferramentas (exceto todo), portanto, pode fazer alterações em arquivos quando necessário. Use isso para executar várias unidades de trabalho em paralelo.

Usar explore

Modo: subagent

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

Usar compaction

Modo: primary

Agente de sistema oculto que compacta longos contextos em um resumo menor. Ele é executado automaticamente quando necessário e não é selecionável na interface.

Usar title

Modo: primary

Agente de sistema oculto que gera títulos curtos para sessões. Ele é executado automaticamente e não é selecionável na interface.

Usar summary

Modo: primary

Agente de sistema oculto que cria resumos de sessões. Ele é executado automaticamente e não é selecionável na interface.

Uso

  1. Para agentes primários, use a tecla Tab para alternar entre eles durante uma sessão. Você também pode usar sua tecla de atalho configurada switch_agent.

  2. Subagentes podem ser invocados:

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

    • Manualmente mencionando um subagente em sua mensagem. Por exemplo.

      @general help me search for this function

  3. 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 tecla de atalho configurada session_child_cycle) para alternar para frente através de pai → child1 → child2 → … → pai
    • <Leader>+Left (ou sua tecla de atalho configurada session_child_cycle_reverse) para alternar para trás através de pai ← child1 ← child2 ← … ← pai

    Isso permite que você mude 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 da configuração. Os agentes podem ser configurados de duas maneiras:

JSON

Configure os agentes em 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 analisar essas opções de configuração em detalhes.

Descrição

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.

Temperatura

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
    }
  }
}

Os valores de temperatura geralmente 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 gerais
  • 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 temperatura for especificada, o opencode usa padrões específicos do modelo; tipicamente 0 para a maioria dos modelos, 0.55 para modelos Qwen.

Máximo de etapas

Controle o número máximo de iterações 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 do agente.

Se isso não for definido, o agente continuará a iterar até que o modelo decida 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 é alcançado, o agente recebe um prompt especial do sistema instruindo-o a responder com um resumo de seu trabalho e tarefas recomendadas restantes.

Desativar

Defina como true para desativar 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 ao local onde o arquivo de configuração está localizado. Portanto, isso funciona tanto para a configuração global do opencode quanto para a configuração específica do projeto.

Modelo

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.

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

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

Ferramentas

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
      }
    }
  }
}

Você também pode usar curingas para controlar várias ferramentas ao mesmo tempo. Por exemplo, para desativar 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.

Permissões

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

  • "ask" — Solicitar aprovação antes de executar a ferramenta
  • "allow" — Permitir todas as operações sem aprovação
  • "deny" — Desativar 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 aceitar 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.

Modo

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.

Oculto

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.

Permissões de tarefa

Controle quais subagentes um agente pode invocar através da ferramenta Task com permission.task. Usa padrões globais 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 da descrição da ferramenta Task completamente, então o modelo não tentará invocá-lo.

Cor

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 hex válida (por exemplo, #FF5733) ou 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 à temperatura 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 são mais diversos.

Adicional

Quaisquer outras opções que você especificar em sua configuração de agente serão passadas diretamente para o provedor como opções de modelo. Isso permite que você use 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 parâmetros disponíveis.

Criar agentes

Você pode criar novos agentes usando o seguinte comando:

Terminal window
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 de sistema apropriado e identificador.
  4. Permitir que você selecione quais ferramentas o agente pode acessar.
  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 e ferramentas de documentação
  • Agente Debug: Focado em investigação com ferramentas bash e de leitura habilitadas
  • Agente Docs: Redação 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.

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