Guia de Integração de Ferramentas de Agentes

PT | EN | ES

Versão: 1.0.0 Última Atualização: 2026-01-26 Status: Referência Oficial

Visão Geral

Este guia explica como ferramentas são integradas com agentes AIOS. Ferramentas estendem as capacidades dos agentes fornecendo acesso a serviços externos, APIs e recursos do sistema.

Arquitetura


┌─────────────────────────────────────────────────────────────┐
│                    Integração de Ferramentas de Agentes      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Definição do Agente (arquivo .md com YAML)               │
│   ┌─────────────────────────────────────────────────────┐   │
│   │  dependencies:                                      │   │
│   │    tools: [git, coderabbit, context7]              │   │
│   │    tasks: [task-a.md, task-b.md]                   │   │
│   │    checklists: [checklist-a.md]                    │   │
│   └─────────────────────────────────────────────────────┘   │
│                           │                                 │
│                           ▼                                 │
│   ┌─────────────────────────────────────────────────────┐   │
│   │  Tipos de Ferramentas                               │   │
│   │  ├── Ferramentas CLI (git, npm, gh)                │   │
│   │  ├── Servidores MCP (EXA, Context7, Apify)          │   │
│   │  └── Serviços Externos (CodeRabbit, Supabase)      │   │
│   └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Declaração de Dependências

Agentes declaram suas dependências no bloco YAML dentro de seu arquivo de definição .md.

Tipos de Dependências

Tipo	Descrição	Localização
`tools`	Ferramentas CLI e serviços externos	PATH do sistema ou MCP
`tasks`	Arquivos de workflow de tarefas	`.aios-core/development/tasks/`
`checklists`	Checklists de validação	`.aios-core/product/checklists/`

Exemplo de Declaração


# Do arquivo .aios-core/development/agents/dev.md
dependencies:
  checklists:
    - story-dod-checklist.md
  tasks:
    - apply-qa-fixes.md
    - create-service.md
    - dev-develop-story.md
    - execute-checklist.md
  tools:
    - coderabbit # Revisão de qualidade de código pré-commit
    - git # Operações locais: add, commit, status, diff
    - context7 # Lookup de documentação de bibliotecas
    - supabase # Operações de banco de dados
    - n8n # Automação de workflows
    - browser # Testes de aplicações web
    - ffmpeg # Processamento de arquivos de mídia

Categorias de Ferramentas por Agente

@dev (Dex - Agente Desenvolvedor)

Ferramenta	Tipo	Propósito
`git`	CLI	Controle de versão (apenas operações locais)
`coderabbit`	Externa	Revisão de qualidade de código pré-commit
`context7`	MCP	Lookup de documentação de bibliotecas
`supabase`	Externa	Operações de banco de dados e migrações
`n8n`	Externa	Automação de workflows
`browser`	MCP	Testes de aplicações web
`ffmpeg`	CLI	Processamento de arquivos de mídia

Restrições de Git para @dev:

Permitido: git add, git commit, git status, git diff, git log, git branch
Bloqueado: git push, gh pr create, gh pr merge
Operações de push requerem o agente @devops

@devops (Gage - Agente DevOps)

Ferramenta	Tipo	Propósito
`git`	CLI	Operações git completas incluindo push
`gh`	CLI	GitHub CLI para operações de PR
`docker`	CLI	Operações de containers
`coderabbit`	Externa	Automação de revisão de código

Capacidades Únicas:

Único agente autorizado para fazer push para remote
Único agente autorizado para criar/fazer merge de PRs
Gerenciamento de infraestrutura MCP

@qa (Quinn - Agente QA)

Ferramenta	Tipo	Propósito
`jest`	CLI	Testes unitários
`playwright`	MCP	Testes E2E e automação de browser
`npm test`	CLI	Executor de testes

@architect (Aria - Agente Arquiteto)

Ferramenta	Tipo	Propósito
`exa`	MCP	Pesquisa e análise
`context7`	MCP	Referência de documentação

Integração MCP

Ferramentas MCP Disponíveis

Servidores MCP (Model Context Protocol) fornecem APIs estruturadas para uso de agentes.

Servidor MCP	Ferramentas Fornecidas	Usado Por
EXA	`web_search_exa`, `company_research_exa`, `get_code_context_exa`	@architect
Context7	`resolve-library-id`, `query-docs`	@dev, @architect
Playwright	`browser_navigate`, `browser_screenshot`, `browser_click`	@qa
Apify	`search-actors`, `call-actor`, `get-actor-output`	@devops

Configuração de MCP

Servidores MCP são configurados via Docker MCP Toolkit. Veja Gerenciamento de Chaves de API do MCP para configuração.

Padrão de Uso


1. Agente recebe tarefa que requer dados externos
2. Agente identifica a ferramenta MCP apropriada de suas dependências
3. Agente chama a ferramenta MCP via interface de ferramentas
4. MCP retorna resposta estruturada
5. Agente processa resposta e continua a tarefa

Integração CodeRabbit

O agente @dev inclui CodeRabbit para verificações de qualidade pré-commit.

Configuração


coderabbit_integration:
  enabled: true
  installation_mode: wsl # ou 'native'
 
  self_healing:
    enabled: true
    type: light
    max_iterations: 2
    timeout_minutes: 15
    trigger: story_completion
    severity_filter:
      - CRITICAL
    behavior:
      CRITICAL: auto_fix
      HIGH: document_only
      MEDIUM: ignore
      LOW: ignore

Workflow

Antes de marcar a story como “Pronto para Revisão”:

Execute CodeRabbit em mudanças não commitadas
Se problemas CRÍTICOS forem encontrados, tente auto-fix (máximo 2 iterações)
Documente problemas ALTOS nas Notas de Dev da story
Se problemas CRÍTICOS permanecerem após iterações, PARE e notifique o usuário

Arquitetura de Restrições de Git

AIOS implementa governança rigorosa de operações git:

Permissões do Agente @dev


git_restrictions:
  allowed_operations:
    - git add
    - git commit
    - git status
    - git diff
    - git log
    - git branch
    - git checkout
    - git merge
  blocked_operations:
    - git push
    - git push --force
    - gh pr create
    - gh pr merge

Permissões do Agente @devops


git_permissions:
  full_access: true
  special_capabilities:
    - push to remote
    - create pull requests
    - merge pull requests
    - admin bypass for branch protection

Workflow de Handoff


@dev completa a story
    ↓
@dev marca status: "Pronto para Revisão"
    ↓
Usuário ativa @devops
    ↓
@devops cria PR e faz push

Adicionando Novas Ferramentas

Passo 1: Atualizar Definição do Agente

Adicione a ferramenta à lista dependencies.tools do agente:


dependencies:
  tools:
    - existing-tool
    - new-tool # Adicione aqui

Passo 2: Documentar Uso da Ferramenta

Se a ferramenta requer configuração específica ou tem padrões de uso especiais, adicione documentação:


tool_integration:
  new-tool:
    purpose: 'Breve descrição'
    common_commands:
      - 'new-tool --help'
      - 'new-tool run <args>'
    when_to_use: 'Use quando condição X é atendida'

Passo 3: Testar Integração

Ative o agente e verifique que a ferramenta é acessível e funcional.

Melhores Práticas

FAÇA

Declare todas as dependências de ferramentas na definição do agente
Use a ferramenta apropriada para cada tipo de tarefa
Siga os limites de permissão do agente
Registre o uso de ferramentas para debug
Valide saídas de ferramentas antes de usar

NÃO FAÇA

Use ferramentas não declaradas em dependências
Contorne restrições de git (use o agente apropriado)
Ignore códigos de retorno de ferramentas
Exponha dados sensíveis em logs de ferramentas
Pule validação de entrada

Troubleshooting

Ferramenta Não Encontrada

Verifique se a ferramenta está instalada: which <tool-name>
Verifique variável de ambiente PATH
Verifique se a ferramenta está declarada nas dependências do agente

Erros de Ferramenta MCP

Verifique se o servidor MCP está rodando
Verifique se as chaves de API estão configuradas (veja Gerenciamento de Chaves de API do MCP)
Revise a documentação específica da ferramenta

Permissão Negada

Verifique se a operação é bloqueada para este agente
Verifique se @devops deveria ser usado no lugar
Verifique permissões de arquivo/diretório

Documentação Relacionada

Mantenedor: @architect (Aria)