Versionamento

O sistema de versionamento permite que você edite assistentes com segurança, mantenha um histórico completo de mudanças e faça rollback quando necessário. O modelo é inspirado no Git: branches, commits e diffs.

Modelo de dados

Assistente
 └── Branch (main, feature/nova-saudacao, ...)
      ├── HEAD → Commit (versão publicada mais recente)
      │    └── CommitFiles → Blobs (conteúdo imutável)
      └── Draft (rascunho em edição)
           └── DraftFiles → Blobs

Commit

Um commit é um snapshot imutável de todos os arquivos do assistente em um momento específico. Cada commit tem:

Campo	Descrição
`id`	Identificador único (12 caracteres hex)
`parent_commit_id`	Commit anterior na cadeia (forma o histórico)
`message`	Descrição opcional da mudança
`author_type`	`"human"`, `"agent"` ou `"system"`
`author_id`	ID do autor (opcional)
`created_at`	Timestamp de criação

Blob

Um blob é o conteúdo de um arquivo (JSONB), armazenado de forma deduplicada por hash SHA-256. Se dois commits tiverem o mesmo conteúdo para um arquivo, ambos apontam para o mesmo blob — economizando espaço.

CommitFile

Mapeia um path (ex: nodes/greeting, tools/check_order) para um blob dentro de um commit específico.

Fluxo de edição

1. Edite o draft     →  PATCH /draft (changeset ou CRUD individual)
2. Verifique mudanças →  GET /branches/{branch_name}/changes
3. Veja o diff        →  GET /branches/{branch_name}/diff
4. Publique           →  POST /branches/{branch_name}/publish → cria novo commit

O draft é uma área de trabalho temporária. As mudanças no draft não afetam o runtime do assistente até serem publicadas.

Branches

Cada assistente começa com uma branch main. Você pode criar branches adicionais para trabalhar em mudanças sem afetar a produção.

main — a branch principal. O endpoint /runtime lê a versão mais recente desta branch.
Branches auxiliares — use para experimentar, testar mudanças antes de fazer merge na main.

Operações com branches

Operação	Descrição
Criar	Cria uma branch a partir do HEAD da `main`
Fork	Copia o draft de uma branch existente para uma nova branch
Publish	Transforma o draft em um commit e avança o HEAD
Merge	Faz merge do HEAD de uma branch no draft da branch de destino
Rollback	Move o HEAD para um commit anterior e reseta o draft

Diff e histórico

Você pode comparar qualquer dois commits para ver exatamente o que mudou:

{
  "diffs": [
    {
      "path": "nodes/greeting",
      "status": "modified",
      "old_content": { "instructions": "Olá!" },
      "new_content": { "instructions": "Olá! Como posso ajudar?" },
      "changes": {
        "instructions": {
          "old": "Olá!",
          "new": "Olá! Como posso ajudar?"
        }
      }
    },
    {
      "path": "tools/track_order",
      "status": "added",
      "old_content": null,
      "new_content": { "name": "Rastrear Pedido" }
    }
  ]
}

O campo status pode ser "added", "modified" ou "removed". Para arquivos "modified", o campo changes mostra um diff superficial (chave por chave) das propriedades que mudaram.

Migração de assistentes legados

Assistentes criados antes do sistema de versionamento (armazenados no Firestore) podem ser migrados para o novo sistema:

POST /assistants/{id}/migrate

A migração:

Lê todo o conteúdo do Firestore (nodes, tools, variables, context)
Escreve no draft da branch main
Publica o commit inicial
Ativa versioning_enabled = true

A migração é irreversível. Uma vez ativado o versionamento, o assistente passa a ler do sistema de versões.

Relacionados

Branches — detalhes sobre o ciclo de vida de branches
Drafts — como funciona a edição de drafts
API de Versões — listar e comparar versões publicadas

Versionamento

On this page