7 blocos fundamentais do design de agentes de IA, a partir da documentação do Opencode

O Opencode está rapidamente a tornar-se a segunda ferramenta de codificação com IA mais discutida, logo a seguir ao Claude Code. Na Coreia, a adoção acelerou graças ao Oh-my-opencode, e as comunidades de desenvolvedores em todo o mundo estão atentas.

Mas o verdadeiro valor do Opencode vai além da assistência na codificação. Por ser open source, é possível inspecionar exatamente como o agente é desenhado - desde o registo de ferramentas até à orquestração de subagentes. Os projetos open source beneficiam das contribuições de desenvolvedores de toda a comunidade, o que significa que a documentação reflete o pensamento mais atual em arquitetura de agentes.

A secção Configure da documentação do Opencode lê-se como um manual introdutório de design de agentes. Estes são os sete blocos fundamentais que ela apresenta e a razão pela qual cada um é importante.

Tools: como os agentes interagem com o mundo

Os Tools definem o que um agente pode fazer. Cada ferramenta é uma capacidade discreta - ler um ficheiro, escrever num ficheiro, executar um comando no terminal, pesquisar na web - registada como uma função invocável.

• O conjunto de ferramentas que forneces determina o limite de capacidades do agente
• As ferramentas são a interface entre o modelo de linguagem e o ambiente externo
• Pela minha experiência, dar ferramentas a mais a um agente é contraproducente: ele passa mais tempo a decidir qual usar do que a executar efetivamente

O princípio de design é direto: um agente sem ferramentas é apenas um chatbot. Um agente com as ferramentas certas torna-se um trabalhador autónomo.

Rules (AGENTS.md): diretrizes de comportamento para os agentes

O AGENTS.md é um formato de ficheiro que fornece contexto e restrições específicas do projeto a um agente. Pensa nele como um README escrito para IA em vez de para humanos.

• Contém diretivas como “nunca alterar código sem testes” ou “seguir esta estrutura de pastas”
• O padrão AGENTS.md já é adotado por mais de 60.000 projetos open source
• As regras moldam a tomada de decisão do agente sem alterar o modelo subjacente

Sem regras, um agente aplica o seu treino genérico ao teu projeto específico. Com regras, aplica as convenções, restrições e preferências do teu projeto. A diferença é substancial.

Agents (subagentes): dividir para conquistar

Tarefas complexas beneficiam de serem divididas entre múltiplos agentes especializados em vez de serem tratadas por um único generalista.

• Podes definir agentes por função: Build, Plan, Review, Debug, entre outros
• Um agente principal cria o plano; os subagentes executam os passos individuais
• Cada subagente opera com um contexto focado, reduzindo o ruído e a deriva das sessões longas com um único agente

É o mesmo princípio dos microsserviços aplicado a fluxos de trabalho de IA. A especialização melhora a qualidade e o isolamento previne a contaminação do contexto.

MCP (Model Context Protocol): um padrão para conexões externas

O Model Context Protocol é um protocolo aberto criado pela Anthropic que padroniza a forma como os agentes se conectam a fontes de dados e serviços externos.

• Fornece uma interface consistente para bases de dados, sistemas de ficheiros, APIs e outras integrações
• Em vez de escrever adaptadores personalizados para cada serviço, o MCP oferece aos agentes uma forma unificada de aceder ao exterior
• Espera-se um ecossistema crescente de aplicações de serviços construídas sobre a camada MCP

O MCP resolve um problema real de interoperabilidade. Antes, cada framework de agentes inventava a sua própria forma de se ligar a ferramentas externas. O MCP torna essas ligações portáteis e combináveis.

LSP (Language Server Protocol): a base para compreender o código

O Language Server Protocol foi originalmente concebido para IDEs, mas provou ser igualmente valioso para agentes de IA que precisam de navegar em bases de código.

• O LSP fornece ir para definição, encontrar referências, autocompletar e diagnósticos
• No Opencode, a integração LSP ainda é experimental, mas melhora significativamente a precisão da navegação no código
• Em vez de depender puramente da pesquisa textual, os agentes podem usar o LSP para compreender semanticamente a estrutura do código

Um agente que consegue seguir uma chamada de função até à sua definição, rastrear todas as referências e compreender hierarquias de tipos opera a um nível fundamentalmente diferente de um que apenas faz correspondência de padrões em strings.

A2A e ACP: padrões para comunicação entre agentes

Quando agentes são construídos com frameworks diferentes, precisam de um protocolo partilhado para colaborar. Dois padrões estão a emergir para preencher esta lacuna.

• A2A (Agent-to-Agent): criado pela Google e doado à Linux Foundation. Define como os agentes se descobrem mutuamente, negoceiam capacidades e trocam mensagens
• ACP (Agent Communication Protocol): construído pela equipa BeeAI e recentemente fundido com a iniciativa A2A

Ambos estão em fases iniciais, mas representam os alicerces de sistemas multiagente onde agentes de diferentes fornecedores e frameworks trabalham juntos sem fricção. A analogia é o HTTP para a web - uma camada de transporte partilhada que torna tudo interoperável.

Skills: pacotes de capacidades reutilizáveis

Os Agent Skills agrupam ferramentas, regras e prompts numa única unidade instalável. Introduzido inicialmente pela Anthropic, este formato está agora padronizado.

• Um agente carrega um skill quando precisa de uma capacidade específica - como revisão de código, fluxo de trabalho TDD ou análise de segurança
• Os skills são partilháveis entre projetos e equipas, criando um ecossistema de comportamentos de agentes reutilizáveis
• Isto sinaliza uma mudança de consumir documentação para consumir skills: em vez de ler como fazer algo, instalas a capacidade de o fazer

Os skills são para os agentes o que os pacotes são para as aplicações. Modularizam a experiência e tornam-na distribuível.

Conclusão

Construir agentes de IA eficazes não é sobre conhecer todas as ferramentas disponíveis. É sobre compreender a arquitetura: como os agentes pensam, como se conectam ao mundo exterior e como colaboram entre si.

Estes sete blocos fundamentais - Tools, Rules, subagentes, MCP, LSP, A2A/ACP e Skills - formam o vocabulário estrutural do design de agentes. Cada um aborda uma preocupação distinta, e juntos definem como é um sistema de agentes bem arquitetado.

Por ser open source, a documentação do Opencode evolui com as contribuições da comunidade de desenvolvedores. Se queres realmente compreender a arquitetura de agentes, a documentação do Opencode merece ser lida.