System Prompts para Agentes de API
Nesta página
Criação de Agentes com grok-build-0.1
Se estiver a desenvolver as suas próprias ferramentas de desenvolvimento — um agente de revisão de código, um assistente de implementação ou uma ferramenta de geração de documentação — irá interagir diretamente com a API da xAI. O system prompt é a sua principal alavanca para controlar o comportamento do modelo.
Anatomia de um Bom System Prompt
Um system prompt eficaz para um agente baseado no grok-build-0.1 contém quatro secções:
1. Descrição da Tarefa
Comece por definir claramente o que o agente faz:
## Função
É um assistente de revisão de código especializado em TypeScript.
Analisa diffs de código para identificar potenciais erros,
problemas de desempenho e violações de convenções.
2. Expectativas e Formato de Saída
Descreva o que espera do modelo:
## Formato de Saída
Para cada problema identificado, forneça:
- O ficheiro e a linha envolvidos
- Gravidade (crítico, aviso, informação)
- Uma descrição do problema
- Uma sugestão de correção com um exemplo de código
3. Casos Limite
Antecipe situações ambíguas:
## Casos Limite
- Se o diff estiver vazio, responda "Sem alterações para analisar"
- Se o código estiver numa linguagem não suportada, indique-o
- Não comente alterações de formatação (espaços, indentação)
- Ignore ficheiros de configuração gerados (.lock, dist/)
4. Restrições
Defina limites:
## Restrições
- Máximo de 10 comentários por revisão
- Priorize erros críticos em detrimento de sugestões de estilo
- Não sugira refatorações maiores para correções menores
Estruturação com Markdown ou XML
O modelo está habituado a receber um contexto substancial e estruturado no primeiro prompt. Dois formatos funcionam bem:
Markdown (Recomendado para Legibilidade)
## Função
Descrição da função...
## Ferramentas Disponíveis
- read_file: ler um ficheiro do projeto
- write_file: modificar um ficheiro
- run_command: executar um comando de terminal
## Regras
1. Leia sempre o ficheiro antes de o modificar
2. Peça confirmação antes de eliminar código
3. Execute os testes após cada modificação
XML (Recomendado para Precisão)
<agent>
<role>Assistente de revisão de código TypeScript</role>
<tools>
<tool name="read_file">Ler um ficheiro do projeto</tool>
<tool name="write_file">Modificar um ficheiro</tool>
</tools>
<rules>
<rule>Leia sempre o ficheiro antes de o modificar</rule>
<rule>Peça confirmação antes de eliminar código</rule>
</rules>
</agent>
Ambos os formatos são eficazes. O Markdown é mais fácil de manter; o XML é mais estruturado para análise automática.
Otimização da Cache
Lembre-se da lição sobre caching: o system prompt deve ser estável. Escreva-o uma vez, na íntegra, e não o modifique durante a sessão. Se precisar de alterar o comportamento do agente, adicione instruções na mensagem do utilizador em vez de modificar o system prompt.
Exemplo Completo: Agente de Geração de Testes
## Função
É um agente que gera testes unitários para código TypeScript.
Utiliza o Vitest como framework de testes.
## Processo
1. Leia o ficheiro de origem com read_file
2. Identifique as funções exportadas
3. Para cada função, gere testes que cubram:
- O caso nominal
- Casos limite (null, undefined, array vazio)
- Casos de erro
4. Escreva os testes com write_file na pasta __tests__/
5. Execute os testes com run_command("npx vitest run")
## Convenções
- Nomenclatura: {file}.test.ts
- Estrutura: describe > it > expect
- Utilize fixtures para dados complexos
- Simule dependências externas (API, BD)
## Restrições
- Não modifique o código de origem
- Se um teste falhar, corrija o teste, não o código de origem
- Máximo de 20 testes por ficheiro
Este system prompt fornece ao agente toda a informação necessária para operar de forma autónoma, mantendo-se dentro dos limites definidos.
Pontos-chave
- O system prompt estrutura o comportamento do agente em 4 partes: função, expectativas, casos limite, restrições
- Utilize Markdown ou XML para estruturar as secções
- O system prompt deve ser estável para otimizar a cache
- Inclua processos passo a passo para agentes sequenciais
- Defina sempre casos limite para evitar comportamentos inesperados
Teste os Seus Conhecimentos
grok-build nos seus editores: assumir o controlo total.
1. O que é o grok-build-0.1?
Resposta: O modelo de código agêntico da xAI: chamada nativa de ferramentas, raciocínio em streaming, contexto adaptado para tarefas de desenvolvimento — o motor por trás do Grok Build e das integrações em editores.
2. Como o utiliza no seu editor?
Resposta: Através de integrações: Cline no VS Code, Cursor, GitHub Copilot, Windsurf e outros — a API da xAI compatível com a OpenAI torna possível a integração direta.
3. Que hábitos garantem boas tarefas de código?
Resposta: Especifique o contexto (ficheiros, restrições), defina objetivos claros e verificáveis, itere progressivamente — e otimize a cache mantendo os prefixos estáveis.
4. grok-build-0.1 ou grok-4.5 para código?
Resposta: grok-build para tarefas agênticas de desenvolvimento diário (rápido, especializado); grok-4.5 quando a tarefa exige o máximo de raciocínio — a escolha segue a dificuldade.
5. O que deve constar no system prompt de um agente de código via API?
Resposta: A função, as convenções do projeto, as regras de edição (testes, estilo) e os limites — o enquadramento que transforma um modelo de código num colega de equipa para a sua base de código.
Modelo especializado, editor conectado, tarefas limpas, prompts enquadrados: o desenvolvimento assistido pelo Grok resume-se a quatro escolhas — todas feitas intencionalmente.