Guia de Configuração do 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 precisa escrever manualmente um prompt do sistema — escolha um predefinido e, se necessário, sobreponha alguns campos.

Predefinição: selecione uma linha de base com base na cena

Um predefinido é um modelo integrado do Agent que agrupa o modelo, o conjunto de ferramentas padrão, o prompt do sistema e a política de execução juntos, nomeado pelo caso de uso. Existem 19 predefinições incorporadas hoje:

Declaração mínima

agents:
  analyst:
    preset: universal

Isso é tudo o que é preciso — modelo, ferramentas e prompt de sistema todos se encaixam nos padrões predefinidos.

Substituições: substituição sob demanda

agents:
  analyst:
    preset: universal
    overrides:
      system_prompt: |
        你是公司的风控分析师。所有输出用中文。
      llm_config:
        models:
          - model: anthropic/claude-sonnet-4-20250514
            provider: openrouter
        temperature: 0.2
      tool_set:
        - file_system
        - web
        - data_transform

Campo de substituições comumente usado

• system_prompt — Substitui o prompt de sistema predefinido por atacado (não anexado).
• llm_config — Configuração do modelo: a lista de modelos (cada entrada um modelo + provedor), retrocesso e temperatura. Cada agente em um workflow pode usar um modelo diferente.
• tool_set — Uma lista de nomes de ferramentas que substitui o padrão predefinido por atacado (sem mesclagem).
• max_iterations — Uma tampa dura nas rodadas internas de "pensar + chamar" do Agente; ele é forçado a parar quando atingido. As predefinições incorporadas fixam isso generosamente.
• strategy — just_work_parallel（Padrão para a maioria das predefinições）/ just_work_parallel_reasoning（Mantém passos de raciocínio visíveis）/ single_run（Saída simples, direta; usada por leve）。
• mcp_servers — Registre um Servidor MCP externo, fundindo as ferramentas que ele expõe no conjunto de ferramentas deste Agente.
• retry_max_attempts / retry_initial_delay / retry_max_delay — A política de retrocesso para chamadas LLM falhadas.

Reutilizável: consulte o Agente na etapa

agents:
  analyst: { preset: universal }
  writer:  { preset: writer }

steps:
  - step: plan
    agent: analyst
    input: "拆解下面这个目标为 3~5 个可执行任务：..."

  - step: write
    agent: writer
    input: "把下面的计划改写成给客户的邮件：{{steps.plan.output}}"
    depends_on: [plan]

O mesmo Agente pode ser referenciado por várias etapas. Cada execução de passos abre uma nova instância de sessão — a memória nunca passa. Para passar dados entre passos, use variáveis de modelo para referenciar saída upstream; para manter o contexto entre rodadas, use state machine ou group chat.

Conjunto de ferramentas (tool_set)

Ferramentas incorporadas são agrupadas pelo nome. Os comuns são:

• file_system — Leia e escreva arquivos no diretório de trabalho.
• shell — Executar comandos de shell.
• web — Pedidos HTTP, raspagem da web e pesquisa.
• browser — Automação do navegador: páginas dinâmicas, formulários, imagens.
• code_execution — Executar trechos de código.
• csv · database · data_transform — Tabelas CSV, bancos de dados SQL e conversão de formato JSON/YAML/XML.
• email · im — Enviando e recebendo e-mail, e mensagens IM (Slack, Telegram, DingTalk, WeCom, Feishu, e muito mais).
• word · excel · powerpoint · pdf · ocr — Geração de documentos e análise.
• image_processing · multimedia — Processamento de imagens e geração de imagens / áudio de IA.
• git — Operações de controlo de versões.
• knowledge_memory — Memória de conhecimento que persiste nas execuções.
• sub_agent — Sub-Agentes Spawn para quebrar uma tarefa.
• skill_tools — Carregar e invocar habilidades.

Todas as definições predefinidas são enviadas com uma ferramenta set padrão; além disso, qualquer agente pode puxar as ferramentas expostas por um Servidor MCP através da configuração mcp servers.

Recomendações de seleção de modelo

• Para tarefas sensíveis à correção (revisão, raciocínio, geração de código): use o modelo emblemático ou de raciocínio de cada provedor.
• Para tarefas sensíveis à latência com saída simples (classificador, resumo curto): use um modelo leve — rápido e barato.
• Você pode misturá-los em um workflow: um modelo barato para análise de alto volume, um mais forte para a revisão final crítica.

Todos os modelos são BYOK: 15+ provedores são suportados (OpenAI, Anthropic, Google, DeepSeek, Kimi, MiniMax, Zhipu, xAI, Mistral, Qwen, e muito mais, além de local Ollama / LM Studio). O uso é faturado em sua própria conta, e credenciais são armazenadas criptografadas com AES-256-GCM. As subscrições Claude Pro / ChatGPT também podem se conectar via login, então uma chave API não é estritamente necessária.

FAQ

Se Várias etapas reutilizarem o mesmo Agente, como a cota será calculada?

Cada execução de passos é uma sessão LLM independente, e o uso de token é gravado por chamada nos detalhes de execução. Planeje os recursos da plataforma de limite de cotas como contagem de workflow, contagem de agendamento e concordância; os tokens LLM são executados em sua própria chave, e a plataforma não define nenhum token cap.

O que devo fazer se houver um loop infinito no Agent?

max iterations é uma tampa dura; a execução é forçada a parar quando é alcançada. Ao solucionar problemas, comece com cada rodada de chamadas de ferramentas na linha do tempo de execução; no Pro e acima, você também pode usar o depurador de pontos de interrupção para pausar e inspecionar dentro de um passo.

Quero adicionar minha própria ferramenta?

Recomendamos empacotá-lo como um servidor MCP e puxá-lo através da configuração mcp servers — não são necessárias alterações de plataforma. Ver Biblioteca de módulos incorporada com Documentação do assistente de IA No capítulo MCP.