Conceitos Principais

Todas as funções do Braidrun – canvas, YAML, agendamento, aprovação, monitoramento – giram em torno de um conjunto muito restrito de conceitos básicos.

Workflow · workflow

Workflow é o objeto de nível superior desta plataforma.

• Um documento YAML (definindo a estrutura)
• Um conjunto de metadados (gatilhos, predefinições de parâmetros, permissões, tags)
• Vários registros de execução anteriores (para auditoria e depuração)

. O mesmo workflow é mostrado como uma tela DAG na interface web; a tela e o YAML são duas visões de uma definição. Diffs no Git são diferenças YAML comuns, não uma lixeira JSON bagunçada.

Um workflow pode ser acionado de cinco maneiras:

1. Manual — Clique em "Executar" no editor ou inicie lotes na lista.
2. Agendado — Uma expressão de cron, um intervalo fixo, uma programação única, ou um gatilho acorrentado que dispara N segundos após um workflow a montante terminar.
3. Webhook — Acionado por um sistema externo POST, autenticado com uma chave API (assinaturas HMAC suportadas para compatibilidade).
4. API — Inicie uma execução do seu próprio sistema usando o endpoint de gatilho da API v1.
5. Incorporado pelo workflow pai — Chamado como caixa preta por outro workflow por meio da etapa sub_workflow.

Passo · Passo

Step é a menor unidade de execução no workflow.

• single — Um único Agente executa uma descrição de tarefa.
• group_chat — Vários agentes discutem alternadamente e referem-se ao contexto uns dos outros.
• agent_based — Um agente orquestrador lê a tarefa e despacha dinamicamente as subtarefas para o agente trabalhador.
• code — 代码脚本（Python / JavaScript / TypeScript / Bash / Ruby / Lua / CLI 共 7 种），在隔离沙箱中执行。确定性 > LLM 的场景首选。
• classifier — O LLM atribui uma legenda de categoria à entrada; o resultado é escrito para a variável nomeada em output variable, para que os passos posteriores possam ramificar nela via condição.
• state_machine — Vários estados + condições de transição de estado.
• sub_workflow — Chame outro workflow como uma caixa preta, com verificação de contrato, detecção de loop e isolamento de variáveis.
• workflow_output_read — Ler saídas publicadas pela execução de outro workflow (publish outputs) e armazená-las em variáveis locais.

Além do modo principal, quase qualquer etapa pode se sobrepor aos seguintes campos de aprimoramento comuns:

• depends_on / condition — Dependências predecessores + condições de skip (condição suporta & & & & & e
• manual_approval — Porta de homologação manual: execução em pausa e continuação após aprovação
• parallel / timeout_seconds — Configuração da execução paralela / tempo- limite
• retry — Estratégia de nova tentativa de backoff para erros transitórios
• repeat_until / iterate_over — Rodar até que uma condição seja satisfeita / iterar sobre um item de coleção por item
• extract / aggregate — Selecione campos de saída/mesclagem de múltiplas entradas
• publish_outputs — Publique artefatos de uma etapa como saídas nomeadas para workflow output read para consumir
• idempotent — Declare "mesma entrada → mesma saída, sem efeitos colaterais"; no autor-resume após um reinício do serviço, ele decide se o passo interrompido pode ser executado novamente
• on_success / on_failure — Ações complementares após sucesso/fracasso (envio de notificações, redação de auditorias, etc.)

Agente·Agente

Um Agente envolve "uma sessão LLM + as ferramentas que ele pode usar + sua política de execução." No Braidrun você quase nunca escreve manualmente um prompt de sistema — escolha um dos 19 predefinições incorporadas (universal / coder / pesquisador / data analyst / web scraper / writer, e assim por diante) e sobreponha alguns campos conforme necessário.

agents:
  planner:
    preset: universal              # 选一个基线模板
  analyst:
    preset: data_analyst
    overrides:                     # 按需覆盖
      llm_config:
        temperature: 0.2
      tool_set: [file_system, csv, database]

Um Agente pode ser referenciado por diversas etapas; Guia de Configuração do Agente.

Módulo · Módulo

Um módulo é um "workflow que declara WorkflowModuleContract" - ou seja, um workflow reutilizável que expõe o contrato de entradas/saídas e pode ser chamado por outros workflows através de sub_workflow.

O valor trazido pelo módulo:

• Verificação do contrato digitado + em nível de campo, não haverá "todos os problemas posteriores se o campo for alterado"
• Execução de caixa preta - o chamador não pode ver as etapas internas e a lógica interna pode evoluir de forma independente
• Detecção de loop duplo em tempo de execução + tempo de liberação para evitar "A faz referência a B e B faz referência a A"
• Promover (extrair uma etapa em um módulo)/Rebaixar (restaurar o módulo para uma etapa embutida) com um clique na biblioteca de módulos

A biblioteca do módulo envia mais de 120 módulos incorporados (início da plataforma, cálculo da janela de tempo, puxar relatório ASA, relatórios Excel, entrega Slack, e muito mais) Biblioteca de módulos incorporada;Crie seu próprio módulo veja Modularização e reutilização.

Execução·Execução

A execução é uma instância específica em execução de um workflow.

PENDING → RUNNING → COMPLETED / FAILED / CANCELLED / INTERRUPTED

Quando atinge uma porta de aprovação, a execução para em um estado de espera-aprovação e retoma a máquina estatal após uma decisão.

Cada execução possui:

• Fonte do gatilho (manual/programação/webhook/api/sub_workflow)
• Hora de início, hora de término, tempo total gasto, tempo gasto por etapa
• Todos os eventos de entrada/saída/intermediários de etapa (fluxo de eventos SSE)
• Token/custo acumulado
• lista de artefatos gerados

Quando o serviço reinicia inesperadamente, as execuções em andamento são marcadas INTERRUPTED. Com recuperação.autoResumeOnRestart ativado, eles podem retomar automaticamente a partir do passo interrompido; veja Retomada automática após reinício do serviço.

Credencial · Credenciais

As credenciais são o armazenamento unificado de informações confidenciais, como "chave de API, segredo do Webhook, token OAuth".

Os links de análise são pesquisados em ordem e o primeiro hit entra em vigor:

1. Namespace pessoal do usuário atual
2. O namespace da equipe do usuário
3. Namespace do sistema (chave pública configurada pelo administrador)

As etapas de agente/código são analisadas sob demanda em tempo de execução, nunca são gravadas em logs, não aparecem nas exportações YAML e não são visíveis para outras etapas do chamador.

Habilidade/Ferramenta · habilidades e Ferramentas

"Mãos" do agente - funções que podem ser chamadas durante a inferência do LLM.

• Conjunto de ferramentas integrado — file_system / shell / web / browser / code_execution Espere, ele estará vinculado por padrão à predefinição.
• MCP Ferramentas de extensão — Qualquer ferramenta exposta pelo servidor MCP pode ser registrada.
• Mercado de Habilidade — Selecione uma habilidade publicada no "Mercado de Habilidades" e ative-a com um clique.

Variáveis e expressões

Todos os valores dinâmicos são passados por chaves duplas {{ ... }} referência. Três formulários:

• {{var:name}} — Uma variável de alto nível de workflow
• {{steps.plan.output}} — Saída de um passo a montante (o formulário totalmente qualificado recomendado)
• {{plan}} — Forma nua: procure primeiro a saída por nome de passo, depois o valor por nome de variável

O resultado de um classificador é escrito para a variável nomeada em seu output variable, e as etapas a jusante usam a condição para decidir qual branch tomar. Credenciais não passam por variáveis de modelo: no tempo de execução eles são resolvidos pelo provedor do centro de credencial e injetados; variáveis entregues a um passo de código são injetadas como variáveis de ambiente WF VAR *.

Para sintaxe completa (JSONPath, filtro, expressões de condição), consulte Variáveis e expressões.

Coloque-os juntos em uma imagem

       ┌──────────── Workflow ────────────┐
       │                                  │
Trigger→─────►  Step 1 (single, agent=A) ◄─── Credential (解析给 A)
       │         │                        │
       │         ▼                        │
       │      Step 2 (classifier)         │
       │         │                        │
       │   ┌─────┴─────┐                  │
       │   ▼           ▼                  │
       │ Step 3       Step 4 (sub_workflow ──► Module)
       │ (code)       │                   │
       │              ▼                   │
       │      manual_approval 门控        │
       │              │                   │
       └──────────────┴──► Execution (记录状态 / 产物 / token / cost)

Você já sabe onde procurar

• Hands-on: Seu Primeiro workflow — Transforme os conceitos acima em um workflow real
• 8 Tipos de passos — Uma referência oficial dedicada ao modo principal
• Variáveis e expressões — Concatenar dados entre etapas
• Glossário — Ao ler outros documentos e encontrar novas palavras, volte e procure-as