Central de Ajuda

Perguntas mais frequentes

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.

1

Como começar a usar

↑ Voltar ao topo

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.

  1. Instale a CLI

    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"
    i
    Não é preciso autenticação nem senha para instalar. O comando baixa a versão mais recente da CLI.
  2. Faça login

    dbuilder login

    Uma 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-code

    Nesse 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.

  3. Escolha o que instalar

    Aqui você decide quais ferramentas de IA quer habilitar. Escolha a opção que faz sentido para você:

    Se você querRode
    Todas as ferramentas e o app desktopdbuilder install --tools all
    Só o app desktop DBuilderdbuilder install --tools desktop
    Só o Claude Codedbuilder install --tools claude
    Só o OpenAI Codexdbuilder install --tools codex
    Só o OpenCode (terminal)dbuilder install --tools opencode
    Uma combinaçãodbuilder install --tools claude,codex
    Claude com o OpenSpecdbuilder install --tools claude --spec

    Na dúvida, instale tudo:

    dbuilder install --tools all
    ✓
    O app desktop já é instalado junto quando você usa --tools all. Depois de instalar, procure por DBuilder Desktop no menu Iniciar. Ele está disponível somente para Windows por enquanto.
  4. Comece a usar

    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.

    ✓
    Se os modelos não aparecerem, rode dbuilder login de novo e reinicie o aplicativo.

O que a instalação traz:

  • Configura as ferramentas de IA que você escolheu, já conectadas aos modelos da empresa e com os modelos que a sua conta pode acessar.
  • Instala as skills que acompanham o pacote, que ensinam a IA a fazer tarefas específicas (veja a lista na seção Como instalar skills?).
  • Instala o RTK, um utilitário que reduz o consumo de tokens durante o uso. Se ele não instalar por algum motivo, nada quebra: basta reabrir o terminal e rodar o comando de novo.

A CLI se atualiza sozinha a cada uso. Para forçar a verificação a qualquer momento, rode dbuilder update.

2

Melhores práticas de uso

↑ Voltar ao topo

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:

  • Os arquivos do projeto (código, documentos, planilhas, etc.).
  • Documentação, requisitos, regras de negócio e exemplos do resultado esperado.
  • Padrões, checklists e templates que você usa no dia a dia.
  • Anotações, links e dados de referência.

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.
i
O AGENTS.md deve ficar na raiz da pasta do projeto e é lido automaticamente em toda sessão.

4. Na conversa, seja específico

  • Diga o objetivo e o resultado esperado, não só o comando.
  • Aponte os arquivos relevantes (ex.: "revise o relatorio.md").
✓
Quanto melhor o contexto (arquivos + AGENTS.md + pedido claro), melhor o resultado e menos idas e vindas.
3

Quantos tokens posso usar?

↑ Voltar ao topo

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.

standard · 5 modelos base + fw-glm-5-2, deepseek moderado
ModeloQuota / dia (tokens)
deepseek-v4-flash20.000.000
gpt-5-4-nano2.000.000
claude-sonnet-4-65.000.000
claude-haiku-4-55.000.000
fw-glm-5-25.000.000
standard_fw · 5 modelos base + fw-glm-5-2 elevado
ModeloQuota / dia (tokens)
deepseek-v4-flash20.000.000
gpt-5-4-nano2.000.000
claude-sonnet-4-65.000.000
claude-haiku-4-55.000.000
fw-glm-5-210.000.000
power · 4 modelos base, deepseek elevado
ModeloQuota / dia (tokens)
deepseek-v4-flash60.000.000
gpt-5-4-nano2.000.000
claude-sonnet-4-65.000.000
claude-haiku-4-55.000.000
fw-glm-5-25.000.000
power_fw · deepseek elevado + fw-glm-5-2 elevado
ModeloQuota / dia (tokens)
deepseek-v4-flash60.000.000
gpt-5-4-nano2.000.000
claude-sonnet-4-65.000.000
claude-haiku-4-55.000.000
fw-glm-5-210.000.000
power_glm · 6 modelos base + fw-glm-5-2, GLM elevado
ModeloQuota / dia (tokens)
deepseek-v4-flash60.000.000
gpt-5-4-nano2.000.000
claude-sonnet-4-65.000.000
claude-haiku-4-55.000.000
fw-glm-5-218.000.000
i
Os valores acima são as máximas diárias por modelo. Não sabe qual é o seu tier? Fale com o time da plataforma.
4

Como ver quantos tokens gastei?

↑ Voltar ao topo

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.

i
Precisa saber seu consumo agora? Solicite ao time da plataforma, que consulta o dashboard do portal.
5

Quando o limite reseta?

↑ Voltar ao topo

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.

6

Como liberar mais tokens?

↑ Voltar ao topo

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:

TierDestaque
standardBase, 5 modelos, deepseek moderado
standard_fwfw-glm-5-2 elevado
powerdeepseek elevado
power_fwdeepseek + fw-glm-5-2 elevados
power_glmGLM elevado

Como funciona:

  • Solicite o upgrade ao time da plataforma, informando o tier desejado.
  • O ajuste é aplicado na subscription do APIM do seu usuário.
  • Depois do upgrade, rode dbuilder install --tools all novamente para atualizar os modelos disponíveis na sua configuração.
✓
Dica: se você bate no limite sempre pelo mesmo modelo, avaliar um tier com esse modelo elevado (ex.: GLM) pode resolver sem aumentar tudo.
7

Agentes, skills, tools e MCPs

↑ Voltar ao topo

Antes de criar agentes e skills, vale entender os quatro recursos que moldam como a IA trabalha no seu projeto:

RecursoO 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.
SkillsPacotes de instruções reutilizáveis para uma tarefa específica (um "como fazer").Padronizar procedimentos, como gerar um release ou seguir um checklist interno.
AgentesPerfis de assistente com prompt, modelo, permissões e modo próprios.Especializar o trabalho, como um revisor somente-leitura ou um arquiteto.
MCPsServidores 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:

  • Tools = o agente faz.
  • Skills = o agente segue um procedimento.
  • Agentes = o agente se especializa.
  • MCPs = o agente se conecta a ferramentas e dados externos.
i
As tools já vêm prontas no DBuilder, você não precisa configurá-las. Já os MCPs consomem contexto, então conecte apenas os que realmente precisa.

Há ainda os comandos (/comando): atalhos reutilizáveis de prompt, úteis para tarefas repetitivas.

8

Como instalar skills?

↑ Voltar ao topo

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.

SkillPara que serve
admin-assistantTarefas administrativas em geral
doc-coauthoringCriar documentos em conjunto, passo a passo
docxCriar e editar arquivos Word (.docx)
email-drafterEscrever e-mails profissionais
file-organizerOrganizar e renomear arquivos e pastas
internal-commsComunicações internas, como comunicados e novidades
invoice-organizerOrganizar notas fiscais e recibos
meeting-notesTransformar anotações de reunião em ata estruturada
pdfCriar, juntar e extrair dados de PDFs
pptxCriar e editar apresentações PowerPoint (.pptx)
weekly-reportMontar relatório semanal de status
xlsxCriar 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:

  • Projeto (só este repositório): .dbuilder/skills/<id>/SKILL.md
  • Global (todos os projetos): ~/.config/dbuilder/skills/<id>/SKILL.md
i
Cada ferramenta tem o seu próprio caminho de skills. No DBuilder Desktop é ~/.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.
!
O ID da skill vem do caminho do arquivo (ex.: 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.

✓
Quer catalogar skills de um time ou servidor? Dá para apontar diretórios/URLs extras no array skills do dbuilder.jsonc.
9

Como criar um agente?

↑ Voltar ao topo

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:

  • Global: ~/.config/dbuilder/agents/<nome>.md
  • Projeto: .dbuilder/agents/<nome>.md

Exemplo: 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:

ModoComportamento
primaryAge como agente principal da sessão (padrão).
subagentRoda só quando chamado por outro agente.
allPode ser principal ou subagente.

Como usar: peça ao agente principal, por exemplo:

Use o subagente reviewer para revisar minhas mudanças atuais.
✓
Também dá para definir agentes diretamente no dbuilder.jsonc, na chave agents, e escolher um agente padrão com default_agent.
10

Dicas e problemas comuns

↑ Voltar ao topo

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çãoO que fazer
Os modelos da empresa não aparecemRode dbuilder login de novo e reinicie o aplicativo.
Erro de cota/limite excedidoVocê 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 funcionaUse obrigatoriamente o e-mail corporativo @db.tec.br.
dbuilder não é reconhecido no terminalFeche 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 meioRode dbuilder install --tools all novamente. O processo pode ser repetido sem problema.