Tudo o que você precisa para instalar, configurar a plataforma, começar a usar e tirar dúvidas sobre cotas, skills, agentes e demais assuntos.
A instalação do DBuilder é feita por uma linha de comando (CLI). Em três comandos você instala, faz login e deixa tudo pronto para usar os modelos da empresa.
Antes de começar: você precisa ter o Node.js 18 ou superior instalado. Para conferir, abra o terminal e rode node --version. Se aparecer v18 ou maior, está tudo certo; se der erro, baixe e instale em nodejs.org/pt-br.
Abra o terminal e rode o comando abaixo:
npm install -g "https://dev.azure.com/db-tecnologia/dbuilder-cli/_apis/git/repositories/dbuilder-cli/items?path=/releases/dbuilder-cli.tgz&download=true&api-version=7.0"dbuilder loginUma página do navegador vai abrir para você entrar com sua conta. Ao terminar, pode fechar a aba.
Se estiver numa máquina sem navegador (servidor remoto, container ou acesso via SSH), use:
dbuilder login --device-codeNesse caso, o terminal mostra um código. Você abre a URL indicada em qualquer outro dispositivo, digita o código e aguarda a confirmação.
Aqui você decide quais ferramentas de IA quer habilitar. Escolha a opção que faz sentido para você:
| Se você quer | Rode |
|---|---|
| Todas as ferramentas e o app desktop | dbuilder install --tools all |
| Só o app desktop DBuilder | dbuilder install --tools desktop |
| Só o Claude Code | dbuilder install --tools claude |
| Só o OpenAI Codex | dbuilder install --tools codex |
| Só o OpenCode (terminal) | dbuilder install --tools opencode |
| Uma combinação | dbuilder install --tools claude,codex |
| Claude com o OpenSpec | dbuilder install --tools claude --spec |
Na dúvida, instale tudo:
dbuilder install --tools all--tools all. Depois de instalar, procure por DBuilder Desktop no menu Iniciar. Ele está disponível somente para Windows por enquanto.Abra a ferramenta que você instalou e escolha a pasta do seu projeto. No seletor de modelos, verifique se os modelos da empresa aparecem na lista.
dbuilder login de novo e reinicie o aplicativo.O que a instalação traz:
A CLI se atualiza sozinha a cada uso. Para forçar a verificação a qualquer momento, rode dbuilder update.
A qualidade da resposta depende do contexto que você oferece. A melhor prática é trabalhar sempre dentro de uma pasta de projeto, com tudo que o agente pode usar como referência.
1. Crie uma pasta para o seu projeto
Crie uma pasta no computador (ex.: Documentos\meu-projeto) e abra o DBuilder apontando para ela. Tudo que estiver nessa pasta pode ser lido pelo agente e vira contexto para as respostas.
2. Alimente a pasta com contexto útil
Coloque ali tudo que ajude o modelo a entender o seu trabalho:
3. Crie um AGENTS.md na raiz da pasta
O arquivo AGENTS.md é lido automaticamente em toda sessão e dá instruções permanentes ao agente. Use-o para comandos, convenções e regras do projeto.
# AGENTS.md (exemplo)
- Este projeto usa React + TypeScript.
- Rode `npm test` antes de considerar uma tarefa concluída.
- Mantenha os textos em português e não use travessão.
- Os dados sensíveis ficam em `config/`. Não altere sem avisar.
AGENTS.md deve ficar na raiz da pasta do projeto e é lido automaticamente em toda sessão.4. Na conversa, seja específico
relatorio.md").AGENTS.md + pedido claro), melhor o resultado e menos idas e vindas.Você pode usar a cota diária do seu tier (plano), contada por modelo, ou seja, cada modelo tem sua própria cota de tokens por dia. Veja abaixo os limites de cada tier.
| Modelo | Quota / dia (tokens) |
|---|---|
| deepseek-v4-flash | 20.000.000 |
| gpt-5-4-nano | 2.000.000 |
| claude-sonnet-4-6 | 5.000.000 |
| claude-haiku-4-5 | 5.000.000 |
| fw-glm-5-2 | 5.000.000 |
| Modelo | Quota / dia (tokens) |
|---|---|
| deepseek-v4-flash | 20.000.000 |
| gpt-5-4-nano | 2.000.000 |
| claude-sonnet-4-6 | 5.000.000 |
| claude-haiku-4-5 | 5.000.000 |
| fw-glm-5-2 | 10.000.000 |
| Modelo | Quota / dia (tokens) |
|---|---|
| deepseek-v4-flash | 60.000.000 |
| gpt-5-4-nano | 2.000.000 |
| claude-sonnet-4-6 | 5.000.000 |
| claude-haiku-4-5 | 5.000.000 |
| fw-glm-5-2 | 5.000.000 |
| Modelo | Quota / dia (tokens) |
|---|---|
| deepseek-v4-flash | 60.000.000 |
| gpt-5-4-nano | 2.000.000 |
| claude-sonnet-4-6 | 5.000.000 |
| claude-haiku-4-5 | 5.000.000 |
| fw-glm-5-2 | 10.000.000 |
| Modelo | Quota / dia (tokens) |
|---|---|
| deepseek-v4-flash | 60.000.000 |
| gpt-5-4-nano | 2.000.000 |
| claude-sonnet-4-6 | 5.000.000 |
| claude-haiku-4-5 | 5.000.000 |
| fw-glm-5-2 | 18.000.000 |
Hoje ainda não é possível ver esse número de forma self-service. O consumo é registrado no gateway (APIM) e o time da plataforma consegue ver no dashboard do portal, com o consumo por usuário. O usuário final ainda não tem acesso a esse dado.
Enquanto isso, dentro do DBuilder você consegue acompanhar o uso de contexto da sessão (quantos tokens a conversa atual está ocupando), e isso ajuda a entender o peso de cada interação, mas não é o total acumulado do seu dia.
A cota reseta automaticamente a cada novo dia. Não é preciso fazer nada. No início do dia seguinte você volta a ter a cota cheia de cada modelo do seu tier.
Para liberar mais tokens, é preciso fazer upgrade de tier, pois o limite é definido pelo tier atribuído ao seu cadastro. Veja os tiers disponíveis:
| Tier | Destaque |
|---|---|
| standard | Base, 5 modelos, deepseek moderado |
| standard_fw | fw-glm-5-2 elevado |
| power | deepseek elevado |
| power_fw | deepseek + fw-glm-5-2 elevados |
| power_glm | GLM elevado |
Como funciona:
dbuilder install --tools all novamente para atualizar os modelos disponíveis na sua configuração.Antes de criar agentes e skills, vale entender os quatro recursos que moldam como a IA trabalha no seu projeto:
| Recurso | O que é | Para que serve |
|---|---|---|
| Tools (ferramentas) | Ações que o agente executa por conta própria: ler e editar arquivos, buscar no projeto, rodar comandos, pesquisar na web. | Deixar o agente agir de verdade no projeto. Você pede o resultado e ele escolhe as ferramentas. |
| Skills | Pacotes de instruções reutilizáveis para uma tarefa específica (um "como fazer"). | Padronizar procedimentos, como gerar um release ou seguir um checklist interno. |
| Agentes | Perfis de assistente com prompt, modelo, permissões e modo próprios. | Especializar o trabalho, como um revisor somente-leitura ou um arquiteto. |
| MCPs | Servidores externos (Model Context Protocol) que adicionam novas ferramentas e dados ao agente. | Integrar sistemas e fontes externas, como consultar uma base de documentação. |
Como isso se encaixa no fluxo de trabalho:
Há ainda os comandos (/comando): atalhos reutilizáveis de prompt, úteis para tarefas repetitivas.
O DBuilder já vem com 12 skills prontas, instaladas junto com a CLI (veja Como começar a usar). Elas são ativadas automaticamente quando fazem sentido para o seu pedido, então você não precisa chamar cada uma.
| Skill | Para que serve |
|---|---|
admin-assistant | Tarefas administrativas em geral |
doc-coauthoring | Criar documentos em conjunto, passo a passo |
docx | Criar e editar arquivos Word (.docx) |
email-drafter | Escrever e-mails profissionais |
file-organizer | Organizar e renomear arquivos e pastas |
internal-comms | Comunicações internas, como comunicados e novidades |
invoice-organizer | Organizar notas fiscais e recibos |
meeting-notes | Transformar anotações de reunião em ata estruturada |
pdf | Criar, juntar e extrair dados de PDFs |
pptx | Criar e editar apresentações PowerPoint (.pptx) |
weekly-report | Montar relatório semanal de status |
xlsx | Criar e editar planilhas Excel (.xlsx) |
Além das skills que já vêm instaladas, você pode criar as suas próprias. Para isso, basta criar um arquivo SKILL.md dentro da pasta de skills. A skill dá ao agente instruções reutilizáveis para uma tarefa específica.
Onde colocar:
.dbuilder/skills/<id>/SKILL.md~/.config/dbuilder/skills/<id>/SKILL.md~/.config/dbuilder/skills/; no Claude Code, ~/.claude/skills/; no Codex, ~/.codex/skills/. O dbuilder install já coloca as skills no lugar certo de cada uma.As skills são descobertas automaticamente: não precisa instalar nada além de criar o arquivo.
Estrutura recomendada (coloque scripts e referências ao lado do SKILL.md):
.dbuilder/skills/
└── git-release/
├── SKILL.md
├── scripts/
│ └── changelog.ts
└── references/
└── release-policy.md
Exemplo de SKILL.md:
---
name: Git Release
description: Preparar notas de release, bump de versão e releases no GitHub
---
## Workflow
1. Ler `references/release-policy.md`.
2. Resumir as mudanças desde a última tag.
3. Propor o bump de versão antes de alterar arquivos.
4. Rodar `scripts/changelog.ts` só depois da aprovação.
git-release), em minúsculas. O campo description é o que faz o modelo descobrir e usar a skill, não deixe de preencher.Como o agente usa: ele carrega a skill pela ferramenta skill quando for relevante. Você também pode forçar a leitura escrevendo @id-da-skill no seu prompt.
skills do dbuilder.jsonc.Para criar um agente, crie um arquivo Markdown que combina um prompt de sistema, um modelo, permissões e um modo de execução em um perfil reutilizável.
Onde colocar:
~/.config/dbuilder/agents/<nome>.md.dbuilder/agents/<nome>.mdExemplo: um revisor somente-leitura:
---
description: Revisa mudanças sem editar arquivos
mode: subagent
model: azure/claude-sonnet-4-6
permissions:
- action: edit
resource: "*"
effect: deny
- action: shell
resource: "*"
effect: deny
---
Revise as mudanças atuais. Liste os achados em ordem de severidade,
com arquivo e linha.
O corpo do Markdown vira o prompt de sistema do agente. O bloco entre --- é a configuração (frontmatter).
Modos:
| Modo | Comportamento |
|---|---|
primary | Age como agente principal da sessão (padrão). |
subagent | Roda só quando chamado por outro agente. |
all | Pode ser principal ou subagente. |
Como usar: peça ao agente principal, por exemplo:
Use o subagente reviewer para revisar minhas mudanças atuais.
dbuilder.jsonc, na chave agents, e escolher um agente padrão com default_agent.Esta seção reúne orientações práticas para o dia a dia: como escolher o modelo certo e o que fazer quando algo não funciona.
1. Como escolher o modelo
No DBuilder há um seletor de modelos. Como cada modelo tem sua própria cota diária, use modelos mais leves (ex.: deepseek-v4-flash, gpt-5-4-nano) para tarefas simples e reserve os maiores para o que exige mais.
2. Problemas comuns e o que fazer
| Situação | O que fazer |
|---|---|
| Os modelos da empresa não aparecem | Rode dbuilder login de novo e reinicie o aplicativo. |
| Erro de cota/limite excedido | Você atingiu a cota diária daquele modelo. Use outro modelo do seu tier ou aguarde a renovação diária. Para aumentar, veja Como liberar mais tokens. |
| Login não funciona | Use obrigatoriamente o e-mail corporativo @db.tec.br. |
dbuilder não é reconhecido no terminal | Feche e abra o terminal novamente. Se persistir, confirme que o Node.js está instalado (node --version) e rode o comando de instalação de novo. |
| A instalação falhou no meio | Rode dbuilder install --tools all novamente. O processo pode ser repetido sem problema. |