Construtor de Agentes IA

Esta página é o guia canônico para construir agentes LLM com o AI Agent Builder da DevUtilities. Use o fluxo guiado acima enquanto lê, ou pule para um tópico abaixo. Schemas, JSON MCP, prompts e contagens de tokens permanecem no seu navegador — nada é enviado para inferência.

AI Agent Builder é uma oficina client-side para montar configs de agentes prontas para produção: ferramentas JSON Schema para function calling da OpenAI, validação mcpServers para Cursor e Claude Desktop, system prompts, orçamentos de tokens combinados e artefatos exportáveis para handoff da equipe.

O que você obtém

• Quatro modos de fluxo: agente completo, só function calling, configuração MCP, resposta estruturada
• Templates iniciais: Filesystem MCP, OpenAI function calling, classificador estruturado
• Inferência exemplo-JSON → JSON Schema com additionalProperties: false estrito opcional
• Lint MCP local com erros e avisos por JSON-pointer
• Orçamento de tokens combinado entre prompt, tools minificadas e JSON MCP
• Exportações: OpenAI tools JSON, response_format, config MCP, resumo markdown, bundle completo

Use este builder quando

• Você precisa de OpenAI tools JSON e não quer escrever JSON Schema à mão
• Você está ligando servidores MCP do Cursor ou Claude Desktop e quer lint antes de colar
• Você deve provar que o prompt + tools de um agente ainda cabem numa janela de contexto
• Você quer uma sessão persistida que encadeia schema → MCP → prompt → export

Prefira uma ferramenta independente quando

• Você só precisa de comparação profunda de encoding ou cálculo de custo → LLM Token Counter
• Você só precisa de lint MCP pontual sem prompts → MCP Validator
• Você só precisa de inferência de schema a partir de uma amostra → Structured Output Generator

Escolha um modo antes de definir tools. Os modos ocultam passos irrelevantes para você não lutar com painéis vazios.

Percurso inicial para um agente completo. Atalhos de template pulam vários destes passos.

1. Escolha Agente completo (ou carregue o template OpenAI function calling).
2. Em Definir tools, adicione cada tool com nome claro, descrição e JSON de argumentos de exemplo representativo.
3. Revise o JSON Schema inferido — ative o modo estrito para structured outputs / strict tool calling da OpenAI.
4. Cole ou edite o JSON mcpServers se o agente for rodar no Cursor ou Claude Desktop; corrija cada erro antes de continuar.
5. Escreva system instructions que digam ao modelo quando chamar cada tool e o que nunca inventar.
6. Abra Orçamento de tokens, escolha cl100k_base ou o200k_base, e confirme que o total combinado cabe no seu modelo.
7. Exporte OpenAI tools JSON para a API, config MCP para o cliente desktop e um resumo markdown para a equipe.
8. Opcionalmente exporte o bundle JSON completo para outro engenheiro recarregar o mesmo estado de sessão depois.

Problema: você precisa de um agente de suporte ao cliente que consulte clima e pedidos via OpenAI function calling, mas o JSON Schema escrito à mão continua falhando na validação estrita.

Como esta ferramenta resolve

1. Selecione o modo Function calling ou carregue o template OpenAI function calling (clima + consulta de pedido).
2. Edite o JSON de exemplo para que cada campo necessário em produção apareça pelo menos uma vez — chaves ausentes não se tornam propriedades required.
3. Ative o modo estrito para que cada objeto emita additionalProperties: false.
4. Aperte o system prompt: confirme IDs de pedido, nunca invente resultados de tools, mantenha respostas concisas.
5. Verifique o orçamento de tokens sob o200k_base se você fizer deploy no GPT-4o.
6. Exporte OpenAI tools JSON e cole no seu cliente Chat Completions ou Responses API.

Resultado: um array de tools estrito e pronto para a API mais um prompt alinhado aos schemas — sem um editor de schema separado.

Problema: Cursor ou Claude Desktop rejeitam seu mcp.json, ou o servidor filesystem inicia com o diretório errado e vê demais do disco.

Como esta ferramenta resolve

1. Escolha o modo Configuração MCP ou carregue o template Filesystem MCP.
2. Substitua /path/to/allowed/dir por um caminho absoluto para o único diretório que o agente pode tocar.
3. Execute a validação — corrija command/args ausentes, URLs inválidas e valores env que não sejam string.
4. Use valores env placeholder (não segredos de produção) enquanto faz lint no navegador.
5. Exporte o JSON mcpServers validado para sua config do Cursor ou Claude Desktop.
6. Adicione system instructions que exijam confirmação antes de operações destrutivas de arquivo.

Resultado: uma config de cliente MCP com lint e um prompt alinhado às capacidades do servidor antes de reiniciar o app desktop.

Problema: você precisa que o modelo retorne sentimento, confiança, tópicos e um resumo curto como JSON — respostas em prosa quebram seu parser downstream.

Como esta ferramenta resolve

1. Escolha o modo Resposta estruturada ou carregue o template de classificador estruturado.
2. Edite o JSON de exemplo para corresponder à forma exata que seu pipeline espera.
3. Ative o modo estrito para que chaves não declaradas sejam rejeitadas na validação.
4. Escreva um system prompt que proíba prosa fora do objeto JSON.
5. Exporte response_format json_schema para structured outputs da OpenAI.
6. Verifique se o orçamento de tokens ainda deixa espaço para o documento de entrada que você classificará.

Resultado: um schema de saída único que você pode inserir em APIs de structured output com instruções correspondentes.

Problema: depois de adicionar três tools e uma config MCP longa, o prompt combinado do agente não cabe mais no orçamento prático do GPT-4o quando o histórico de chat é incluído.

Como esta ferramenta resolve

1. Abra o passo Orçamento de tokens e anote o total combinado de prompt + tools minificadas + JSON MCP.
2. Encurte descrições de tools e remova campos de exemplo não usados que inflam schemas required.
3. Mova texto de política verboso para fora do system prompt sempre ativo, para recuperação sob demanda.
4. Se você só precisa de matemática de encoding mais profunda, copie o payload montado para o LLM Token Counter.
5. Reexporte só quando o orçamento mostrar folga confortável para histórico e completions.

Resultado: você captura o overflow no builder — não depois do primeiro erro 400 em produção.

O JSON de exemplo deve ser JSON estrito. Só as chaves presentes no exemplo se tornam propriedades required. Objetos e arrays aninhados inferem tipos a partir dos valores de amostra.

Regras práticas

• Inclua cada campo que o modelo deve poder enviar — omitir significa “não required”, não “opcional com um default”.
• Use enums realistas como amostras string e depois edite o schema à mão se precisar de um array enum explícito.
• Ative o modo estrito para emitir additionalProperties: false em cada objeto — recomendado para structured outputs e strict tool calling da OpenAI.
• Arrays vazios inferem tipos de item fracos — adicione pelo menos um elemento representativo.

Servidores stdio precisam de command e tipicamente args. Servidores remotos precisam de uma url http ou https válida. Valores env devem ser strings. Erros bloqueiam a confiança de exportação; avisos merecem uma passagem manual.

Envelopes de cliente comuns

• A chave de nível superior deve ser "mcpServers" conforme as convenções do Cursor e Claude Desktop
• Servidores filesystem devem usar caminhos absolutos em allow-list
• Prefira placeholders env ao editar no navegador; injete segredos reais só na máquina local

As contagens de tokens combinam system prompt, schemas de tools minificadas e JSON MCP. Escolha cl100k_base para aproximação GPT-4 / Claude ou o200k_base para GPT-4o. As contagens usam tabelas tiktoken locais — sem chamadas de API.

• Trate o número como um piso: histórico de chat e resultados de tools adicionam mais em runtime
• Verifique de novo após cada edição de schema ou prompt
• Use LLM Token Counter quando precisar de mapas de limites ou cartões de custo mensal em um payload personalizado

Sintomas: a OpenAI rejeita o payload de tools, ou o modelo não consegue passar argumentos que seu app realmente precisa.

Por que acontece

Schemas estritos rejeitam chaves não declaradas. Se o JSON de exemplo omitiu um campo, ele nunca virou propriedade. Se o modo estrito estiver desligado, os limites de structured output da OpenAI ainda podem rejeitar objetos abertos.

Diagnosticar

Compare as properties do schema inferido com os argumentos que sua aplicação envia. Confirme que o modo estrito está ativado ao mirar structured outputs da OpenAI.

Correções

1. Adicione as chaves ausentes ao JSON de exemplo e regenere o schema.
2. Ative o modo estrito para que additionalProperties: false seja consistente em objetos aninhados.
3. Encurte construções não suportadas (oneOf profundamente aninhado, tipos exóticos) conforme os limites de structured output da OpenAI.
4. Reexporte tools JSON e reteste com um payload de argumentos conhecido e válido.

Sintomas: erros de validação em command/url, o cliente falha ao iniciar o servidor, ou o transporte remoto nunca conecta.

Por que acontece

Entradas stdio sem command, remotas sem URLs http(s), valores env numéricos ou chaves de nível superior erradas quebram os parsers do cliente.

Diagnosticar

Leia o JSON pointer de cada erro de lint. Confirme que o envelope usa mcpServers e que cada servidor é stdio (command) ou remoto (url), não um híbrido quebrado.

Correções

1. Adicione command e args para servidores stdio; cite todos os valores env como strings.
2. Use URLs http:// ou https:// para transportes MCP remotos.
3. Corrija o nome da chave de nível superior para mcpServers.
4. Reexecute a validação até zerar erros; priorize avisos antes de publicar.

Sintomas: API keys aparecem no JSON exportado, diffs de git ou capturas do builder.

Por que acontece

Blocos env de MCP são JSON puro. Colar segredos de produção numa ferramenta do navegador — mesmo local — aumenta o risco de vazamento via clipboard, compartilhamento de tela e commits acidentais.

Diagnosticar

Procure nas exportações e no painel MCP padrões sk-, Bearer ou chaves de fornecedor. Confirme que configs commitadas só contêm placeholders.

Correções

1. Substitua segredos por placeholders no estilo ${ENV_VAR} no builder.
2. Injete valores reais só no cliente desktop local ou no secret store do deploy.
3. Rotacione qualquer chave colada em chat, tickets ou telas compartilhadas.
4. Adicione um scan de segredos pre-commit para mcp.json e arquivos de bundle do agente.

Este workspace não envia sua config — mas clipboard e git ainda podem vazá-la.

• Nunca faça commit de API keys em blocos env MCP — use placeholders de variáveis de ambiente
• Use caminhos absolutos de menor privilégio para servidores MCP filesystem
• Revise o orçamento de tokens antes de adicionar exemplos few-shot grandes a prompts de produção
• Prefira schemas estritos para que tools não aceitem chaves inesperadas
• Trate bundles exportados como sensíveis se contiverem nomes de tools internos ou hosts de infra

• Comece de um template e depois remova tools que não precisa — schemas menores são mais baratos e seguros
• Nomeie tools com verbos claros (lookup_order, get_weather) alinhados às instruções do system prompt
• Mantenha uma única fonte da verdade: exporte deste builder em vez de manter cópias de schema divergentes
• Revalide MCP após cada mudança de caminho ou command
• Documente o orçamento de tokens no export markdown para revisores verem o impacto de custo nos PRs
• Use LLM Token Counter para diffs profundos de encoding; use este builder para o agente montado