Drafts

O draft é a área de trabalho de uma branch. Todas as edições acontecem no draft — adicionando, atualizando ou removendo nodes, tools, variables, context e config. Mudanças no draft não afetam o runtime até serem publicadas.

Duas formas de editar

1. Changeset (recomendado)

O changeset permite aplicar múltiplas mudanças em uma única requisição:

PATCH /assistants/{id}/branches/{branch_name}/draft

{
  "context": { "assistant_name": "Novo Nome" },
  "config": { "initial_node_id": "welcome" },
  "nodes": {
    "upsert": [{ "id": "welcome", "name": "Boas-vindas", "type": "llm", ... }],
    "delete": ["old_node_id"]
  },
  "tools": {
    "upsert": [{ "id": "search", "name": "Buscar", ... }],
    "delete": []
  },
  "variables": {
    "upsert": [{ "id": "user_name", "name": "Nome do Usuário", ... }],
    "delete": []
  }
}

Todos os campos são opcionais — envie apenas o que mudou.

2. CRUD individual

Para edições pontuais, use os endpoints específicos de cada tipo:

Tipo	Endpoints
Nodes	`GET/PUT/PATCH/DELETE /draft/nodes/{id}`
Tools	`GET/PUT/PATCH/DELETE /draft/tools/{id}`
Variables	`GET/PUT/PATCH/DELETE /draft/variables/{id}`
Config	`GET/PUT/PATCH /draft/config`
Context	`GET/PUT/PATCH /draft/context`

Use PUT para criar ou substituir completamente, PATCH para atualização parcial.

Atualizado

PATCH segue RFC 7396 JSON Merge Patch:

Campos omitidos são preservados.
null remove a chave.
Objetos aninhados são mesclados recursivamente — um PATCH com { "config": { "model": "openai:gpt-5.4" } } troca apenas o model e preserva o restante do config (instructions, next_node, tools, etc.).
Arrays são substituídos por inteiro (não mesclados item a item).

Lendo o draft

Snapshot completo

GET /assistants/{id}/branches/{branch_name}/draft

Retorna o AssistantSnapshot montado a partir de todos os arquivos do draft — o mesmo formato do /runtime.

Filtrar por prefixo

GET /assistants/{id}/branches/{branch_name}/draft?prefix=nodes/

Retorna apenas os arquivos que começam com o prefixo (útil para listar só nodes ou só tools).

Índice de arquivos

GET /assistants/{id}/branches/{branch_name}/draft/index

Lista apenas os paths dos arquivos no draft, sem conteúdo:

["context", "config", "nodes/greeting", "nodes/farewell", "tools/check_order"]

Descartando mudanças

Descartar um arquivo

Reverte um único arquivo do draft para o estado do HEAD:

POST /assistants/{id}/branches/{branch_name}/draft/discard
{ "path": "nodes/greeting" }

Resetar todo o draft

Reseta todos os arquivos do draft para o estado de um commit específico:

POST /assistants/{id}/branches/{branch_name}/draft/reset
{ "commit_id": "c3d4e5f6a1b2" }

Tipos de arquivos

Node

{
  "id": "greeting",
  "name": "Saudação",
  "description": "Node inicial de boas-vindas",
  "type": "llm",
  "config": {
    "node_type": "llm",
    "instructions": "Cumprimente o cliente.",
    "next_node": "router_1",
    "tools": ["check_order"]
  },
  "position": { "x": 100, "y": 200 }
}

Tipos de node: llm, classifier, router, logic, skill.

Tool

{
  "id": "check_order",
  "name": "Consultar Pedido",
  "description": "Consulta o status de um pedido",
  "request": {
    "url": "https://api.example.com/orders/{order_id}",
    "method": "GET"
  },
  "parameters": { ... },
  "should_close": false
}

Variable

{
  "id": "user_name",
  "name": "Nome do Usuário",
  "permission": "read_write",
  "type": "string",
  "default_value": null
}

Context

{
  "assistant_name": "Suporte ao Cliente",
  "assistant_description": "Assistente de suporte para e-commerce"
}

Config

{
  "initial_node_id": "greeting"
}

Relacionados

API de Drafts — referência completa dos endpoints
Início Rápido — exemplo prático de edição e publicação

Drafts

On this page