Autoria de Agente com LLM

invowk agent cmd e invowk agent mod ajudam agentes LLM a criar e alterar comandos personalizados e módulos locais válidos sem adivinhar o contrato CUE atual.

Prompt para Agentes Externos

Use prompt quando outro agente ou ferramenta fará a edição. A saída é um system prompt por operação com os schemas completos e atuais de invowkfile.cue e invowkmod.cue, além de orientação específica do Invowk sobre runtimes, dependências, visibilidade de comandos, limites de módulos e defaults seguros.

# Print operation-aware command prompts for an external agent
invowk agent cmd prompt
invowk agent cmd prompt change --format json

# Print operation-aware module prompts
invowk agent mod prompt
invowk agent mod prompt create --format json

Gerar ou Alterar

Use create e change quando o Invowk deve chamar o provedor LLM configurado, validar o CUE gerado e aplicar patch apenas nos arquivos de destino permitidos. A autoria de comandos atualiza invowkfile.cue; a autoria de módulos atualiza apenas invowkmod.cue e invowkfile.cue dentro do módulo de destino.

# With no configured provider, use an OpenAI-compatible local server
invowk agent cmd create docs --llm --llm-url http://localhost:1234/v1 'add a docs build command'

# Configure once, then generate without per-run LLM flags
invowk config set llm.provider codex
invowk agent cmd create lint 'add a lint command that runs golangci-lint'

# Generate and patch invowkfile.cue using the best available provider
invowk agent cmd create test --llm-provider auto 'add a test command'

# Change or remove an existing command
invowk agent cmd change lint --llm-provider claude 'run golangci-lint with --fix support'
invowk agent cmd remove lint --dry-run

# Preview the patch without writing
invowk agent cmd create release --llm-provider codex --dry-run 'add a release command'

# Print only the generated command object
invowk agent cmd create checklist --llm-provider claude --print 'add a release checklist command'

# Create, change, or remove a local module
invowk agent mod create io.example.tools --llm-provider codex 'create portable project tools'
invowk agent mod change io.example.tools --llm-provider codex 'add a formatting command'
invowk agent mod remove io.example.tools --dry-run

Os comandos de autoria que usam LLM aceitam as mesmas flags de provedor LLM de invowk audit: --llm-provider, --llm, --llm-url, --llm-model, --llm-api-key, --llm-timeout e --llm-concurrency.

Configure llm.provider ou llm.api uma vez em config.cue para omitir flags LLM nas próximas execuções de create/change:

invowk config set llm.provider codex
invowk agent cmd create lint 'add a lint command that runs golangci-lint'

Veja Opções de Configuração para exemplos de provider e API. Chaves de API brutas devem ficar em variáveis de ambiente, referenciadas com llm.api.api_key_env.

Comportamento de Escrita

agent cmd create exige <name> e falha se esse comando já existe; use agent cmd change <name> para atualizar um comando existente. agent mod create exige <module-id> e falha se <module-id>.invowkmod já existe; use agent mod change <module-id-or-path> para atualizar um módulo local existente. Use --dry-run para visualizar patches e --print para imprimir a saída gerada sem escrever. --verify valida o módulo escrito ou resolve o comando escrito com um plano de execução dry-run.

:::caution O conteúdo do prompt é enviado ao provedor configurado Operações create/change com LLM enviam o system prompt e schemas de autoria gerados, além de um prompt de usuário contendo sua solicitação e o caminho de destino. Criar ou alterar um comando em um invowkfile existente também envia o conteúdo atual desse arquivo; alterar um módulo envia seus arquivos de módulo atuais. Se o modelo retorna saída inválida, a tentativa de reparo também envia o erro de validação e a resposta anterior do modelo. Use um provedor local quando definições de comandos ou arquivos de módulo tiverem detalhes privados do projeto. :::

Validação

O Invowk aceita apenas um objeto de comando gerado para autoria de comandos, e o name gerado deve corresponder ao <name> solicitado. A autoria de módulos aceita apenas conteúdo gerado para invowkmod.cue e invowkfile.cue, e invowkmod.cue deve manter o ID de módulo solicitado. O Invowk usa saída JSON estruturada com backends de API OpenAI compatíveis, tenta novamente uma vez com feedback de validação quando um modelo retorna saída inválida e rejeita JSON malformado, CUE inválido, arrays cmds completos em command_cue e arquivos extras arbitrários em módulos gerados.

Operações de remoção são determinísticas: agent cmd remove <name> edita o invowkfile de destino sem resolver um provedor LLM, e agent mod remove <module-id-or-path> valida o módulo local exato e exige --force, exceto com --dry-run.