claude-to-deerflow

Skill DeerFlow

Comunique-se com uma instância do DeerFlow em execução por meio de sua API HTTP. DeerFlow é uma plataforma de agentes de IA construída em LangGraph que orquestra subagentes para pesquisa, execução de código, navegação na web e muito mais.

Arquitetura

O DeerFlow expõe duas superfícies de API atrás de um proxy reverso Nginx:

Serviço	Porta Direta	Via Proxy	Finalidade
API Gateway	8001	$DEERFLOW_GATEWAY_URL	Endpoints REST e runtime de agente incorporado
API compatível com LangGraph	8001	$DEERFLOW_LANGGRAPH_URL	Threads de agente, execuções, streaming

Variáveis de Ambiente

Todas as URLs são configuráveis por meio de variáveis de ambiente. Leia essas variáveis de ambiente antes de fazer qualquer requisição.

Variável	Padrão	Descrição
DEERFLOW_URL	http://localhost:2026	URL base do proxy unificado
DEERFLOW_GATEWAY_URL	${DEERFLOW_URL}	URL base da API do Gateway (modelos, skills, memória, uploads)
DEERFLOW_LANGGRAPH_URL	${DEERFLOW_URL}/api/langgraph	URL base da API LangGraph (threads, execuções)

Ao fazer chamadas curl, sempre resolva as URLs assim:

# Resolver URLs base a partir do ambiente (faça isso PRIMEIRO antes de qualquer chamada à API)
DEERFLOW_URL="${DEERFLOW_URL:-http://localhost:2026}"
DEERFLOW_GATEWAY_URL="${DEERFLOW_GATEWAY_URL:-$DEERFLOW_URL}"
DEERFLOW_LANGGRAPH_URL="${DEERFLOW_LANGGRAPH_URL:-$DEERFLOW_URL/api/langgraph}"

Operações Disponíveis

1. Verificação de Saúde

Verifique se o DeerFlow está em execução:

curl -s "$DEERFLOW_GATEWAY_URL/health"

2. Enviar uma Mensagem (Streaming)

Esta é a operação principal. Ela cria uma thread e transmite a resposta do agente.

Passo 1: Criar uma thread

curl -s -X POST "$DEERFLOW_LANGGRAPH_URL/threads" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta: {"thread_id": "<uuid>", ...}

Passo 2: Transmitir uma execução

curl -s -N -X POST "$DEERFLOW_LANGGRAPH_URL/threads/<thread_id>/runs/stream" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "lead_agent",
    "input": {
      "messages": [
        {
          "type": "human",
          "content": [{"type": "text", "text": "SUA MENSAGEM AQUI"}]
        }
      ]
    },
    "stream_mode": ["values", "messages-tuple"],
    "stream_subgraphs": true,
    "config": {
      "recursion_limit": 1000
    },
    "context": {
      "thinking_enabled": true,
      "is_plan_mode": true,
      "subagent_enabled": true,
      "thread_id": "<thread_id>"
    }
  }'

A resposta é um stream SSE. Cada evento tem o formato:

event: <tipo_evento>
data: <dados_json>

Tipos de evento principais:

• metadata — metadados da execução, incluindo run_id
• values — instantâneo completo do estado com array messages
• messages-tuple — atualizações incrementais de mensagens (pedaços de texto de IA, chamadas de ferramenta, resultados de ferramenta)
• end — stream completo

Modos de contexto (definidos via context):

• Modo Flash: thinking_enabled: false, is_plan_mode: false, subagent_enabled: false
• Modo Padrão: thinking_enabled: true, is_plan_mode: false, subagent_enabled: false
• Modo Pro: thinking_enabled: true, is_plan_mode: true, subagent_enabled: false
• Modo Ultra: thinking_enabled: true, is_plan_mode: true, subagent_enabled: true

3. Continuar uma Conversa

Para enviar mensagens de acompanhamento, reutilize o mesmo thread_id do passo 2 e faça um POST de outra execução com a nova mensagem.

4. Listar Modelos

curl -s "$DEERFLOW_GATEWAY_URL/api/models"

Retorna: {"models": [{"name": "...", "provider": "...", ...}, ...]}

5. Listar Skills

curl -s "$DEERFLOW_GATEWAY_URL/api/skills"

Retorna: {"skills": [{"name": "...", "enabled": true, ...}, ...]}

6. Ativar/Desativar uma Skill

curl -s -X PUT "$DEERFLOW_GATEWAY_URL/api/skills/<nome_skill>" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

7. Listar Agentes

curl -s "$DEERFLOW_GATEWAY_URL/api/agents"

Retorna: {"agents": [{"name": "...", ...}, ...]}

8. Obter Memória

curl -s "$DEERFLOW_GATEWAY_URL/api/memory"

Retorna contexto do usuário, fatos e resumos do histórico da conversa.

9. Enviar Arquivos para uma Thread

curl -s -X POST "$DEERFLOW_GATEWAY_URL/api/threads/<thread_id>/uploads" \
  -F "files=@/caminho/para/arquivo.pdf"

Suporta PDF, PPTX, XLSX, DOCX — converte automaticamente para Markdown.

10. Listar Arquivos Enviados

curl -s "$DEERFLOW_GATEWAY_URL/api/threads/<thread_id>/uploads/list"

11. Obter Histórico da Thread

curl -s "$DEERFLOW_LANGGRAPH_URL/threads/<thread_id>/history"

12. Listar Threads

curl -s -X POST "$DEERFLOW_LANGGRAPH_URL/threads/search" \
  -H "Content-Type: application/json" \
  -d '{"limit": 20, "sort_by": "updated_at", "sort_order": "desc"}'

Script de Uso

Para enviar mensagens e coletar a resposta completa, use o script auxiliar:

bash /caminho/para/skills/claude-to-deerflow/scripts/chat.sh "Sua pergunta aqui"

Veja scripts/chat.sh para a implementação. O script:

1. Verifica a saúde
2. Cria uma thread
3. Transmite a execução e coleta a resposta final da IA
4. Imprime o resultado

Analisando a Saída SSE

O stream retorna eventos SSE. Para extrair a resposta final da IA de um evento values:

• Procure pelo último bloco event: values
• Analise seu JSON data
• O array messages contém todas as mensagens; a última com type: "ai" é a resposta
• O campo content dessa mensagem é a resposta de texto da IA

Tratamento de Erros

• Se a verificação de saúde falhar, o DeerFlow não está em execução. Informe ao usuário que ele precisa iniciá-lo.
• Se o stream retornar um evento de erro, extraia e exiba a mensagem de erro.
• Problemas comuns: porta não aberta, serviços ainda iniciando, erros de configuração.

Dicas

• Para perguntas rápidas, use o modo Flash (mais rápido, sem planejamento).
• Para tarefas de pesquisa, use o modo Pro ou Ultra (permite planejamento e subagentes).
• Você pode enviar arquivos primeiro e depois referenciá-los em sua mensagem.
• Os IDs de thread persistem — você pode retornar a uma conversa posteriormente.