🛰️ Avançado II — Plataforma

O provider padrão do DeerFlow usa a interface ChatOpenAI do LangChain e aceita um base_url arbitrário — qualquer servidor OpenAI-compatible entra sem código novo.

Apontar o base_url para OpenRouter ou LiteLLM libera dezenas de modelos pagando numa única conta, sem reescrever provider no harness.

base_url; api_key por provider; header extras; modelos disponíveis por gateway; fallback cross-provider.

Flag do provider que troca a chamada de /v1/chat/completions para /v1/responses, habilitando o novo formato da OpenAI com tools, state e streaming aprimorado.

A Responses API é o caminho oficial para features novas da OpenAI; saber ligar é a diferença entre seguir o roadmap ou ficar travado.

use_responses_api; diferenças de payload; tool calling no novo formato; compatibilidade com middleware existente.

vLLM é um servidor inference open-source de alta performance; o DeerFlow tem um VllmChatModel dedicado para falar com ele servindo Qwen3, DeepSeek e similares localmente.

Self-hosting é a única saída para dados sensíveis, custos previsíveis em escala e ambientes offline — e vLLM é o padrão da indústria.

vLLM server; modelo carregado; VllmChatModel; tool calling em modelos open-weights; throughput vs. latência.

Modo em que o harness conversa com outro agente CLI (Codex CLI da OpenAI, Claude Code via OAuth) como se fosse um provider de LLM — reaproveitando billing e auth daquele CLI.

É a forma mais barata de ter acesso a modelos de topo sem nova conta de API: você usa a assinatura pessoal do CLI já logado.

Codex CLI provider; Claude Code OAuth; proxy stdio; limites de cada CLI; cuidados com ambientes compartilhados.

Framework mental para decidir entre modelos: quanto custa por task, qual a latência percebida e o quão bem ele resolve o tipo de problema que você tem.

Escolher modelo errado triplica a conta ou piora a experiência — a decisão é por skill/agent, não global.

Custo por task; TTFT; p95 de latência; benchmarks internos; model-per-role; routing condicional.

Rodar a mesma skill de pesquisa em três providers diferentes (ex.: OpenAI, Claude Code CLI e vLLM Qwen3 local) e comparar traces, tokens e tempo.

Números reais desmontam crença — o modelo "mais caro" nem sempre vence, e o self-hosted nem sempre compensa.

Dataset fixo de queries; mesma skill; export dos traces; planilha de custo; conclusão escrita do trade-off.

Revisão dos modos de sandbox já vistos na Trilha 1, mas agora perguntando para cada um: o que acontece se a tool executar código hostil?

A escolha do sandbox é a linha entre "agente útil" e "servidor comprometido" — e muita gente acerta por sorte.

Ameaça vs. modo; raiz do host; namespaces; egress network; persistência entre execuções.

Como o DeerFlow limita CPU, memória, disco e rede dentro da sandbox Docker/K8s, e como a imagem base restringe o que pode ser instalado.

Sem quotas, um bug do agente come sua máquina inteira. Sem imagem fechada, qualquer pip install vira porta de ataque.

cgroups; resource limits do K8s; allow-list de pacotes; imagem mínima; rootless; seccomp/AppArmor.

Percorrer o SECURITY.md do repositório explicando cada recomendação: ameaças cobertas, contramedidas e processo de disclosure.

É o documento mais autoritativo do projeto sobre risco — e a maioria dos usuários nunca o abre.

Threat model; supported versions; reporting channel; timelines; escopo fora do threat model.

Lista curada de "armadilhas de deploy" — configurações que funcionam em dev mas viram buraco de segurança em produção.

A maior parte dos incidentes em agentes vem dos mesmos 4 ou 5 erros. Decorá-los evita todos eles.

Sandbox Local em prod; API sem auth; secrets no prompt; tool irrestrita; logs vazando PII.

Deploy do DeerFlow no modo K8s com provisioner e execução de um script intencionalmente hostil para validar que o isolamento funciona e que o incidente é detectado.

Testar a sandbox com hostil de mentira é a única forma honesta de saber se ela aguenta hostil de verdade.

K8s provisioner; Pod quotas; script de teste; assinatura do incidente; coleta de evidências; tabela de resultado esperado.

Leitura guiada do MEMORY_IMPROVEMENTS.md e docs vizinhos que descrevem como a memória do DeerFlow evoluiu e como ela se comporta hoje em regime de produção.

Memória é onde a maioria das surpresas estranhas nascem; o doc oficial responde 80% das dúvidas antes de virarem bug.

Camadas de memória; store backend; políticas de TTL; métricas de hit rate; histórico de decisões.

Políticas que detectam janela cheia, resumem trechos antigos preservando o essencial e devolvem memória útil no próximo turno.

Sem compactação boa, conversas longas degeneram silenciosamente — o modelo perde contexto e ninguém sabe por quê.

Threshold de compactação; summarization rolling; pinning de mensagens críticas; verificação de perda de info.

Mecanismo que, a cada turno, recupera apenas as memórias mais relevantes para a mensagem atual — usando embeddings ou heurísticas de tag/tempo.

Jogar "toda memória" no prompt é lento, caro e quebra a atenção do modelo. Recall certeiro é o caminho do meio.

Embeddings; similarity threshold; filtros por tag/agent; re-ranking; orçamento de tokens por recall.

Memory poisoning é quando conteúdo malicioso ou simplesmente errado entra na memória e começa a influenciar todas as respostas seguintes do agente.

É um dos ataques mais difíceis de detectar — e também acontece sem ataque, por bug simples de escrita de memória.

Validação antes de gravar; marcas de origem; TTL forçado; sobrescrita idempotente; auditoria periódica.

Escrever um teste end-to-end que cria uma memória, atualiza o valor, consulta e verifica que o valor antigo não volta a aparecer no prompt.

Comportamento de "atualização" de memória é intuitivo no papel e cheio de pegadinha no código — teste é a única prova.

Fixture de memória; múltiplos turnos; asserts no prompt final; regressão futura; cobertura em CI.

Modo "import deerflow" em que o harness roda dentro do seu processo Python, sem subir servidor; ideal para notebooks, jobs e apps próprias.

É a porta para usar o DeerFlow dentro de pipelines, dashboards e backends existentes — sem refatorar nada do seu código.

Embedded client API; ciclo de vida do harness; config via dict; gestão de threads/async; encerramento limpo.

Quando embutir direto não cabe, o DeerFlow expõe um API gateway HTTP com endpoints documentados — chat, streaming, histórico, title.

O gateway é o contrato que isola sua app do harness, permitindo upgrade do core sem quebrar frontend ou integrações.

Endpoints; auth; schema; versão da API; OpenAPI/docs; compatibilidade retroativa.

Feature que, a partir das primeiras mensagens da conversa, gera automaticamente um título curto e útil para aparecer na sidebar do app.

Parece detalhe, mas é o que faz uma lista de conversas ser útil — sem ela, a app vira um monte de "New chat".

Endpoint de title; modelo cheap; prompt de titulação; cache; quando regenerar.

Endpoint que emite eventos em tempo real (SSE) conforme o grafo progride: tokens, tool calls, resultados, erros — pronto para plugar em UIs reativas.

Streaming não é só "resposta digitando"; é a forma correta de mostrar o agente pensando, criando confiança no usuário.

SSE vs. WebSocket; tipos de evento; reconexão; backpressure; encerramento gracioso.

Construir uma pequena aplicação Python (script ou FastAPI) que importa o Embedded Client, roda uma skill existente e consome o resultado.

Sair do "uso pelo CLI" para o "uso programático" é o divisor de águas entre brincar e construir produto.

Instalação como dependência; config mínima; chamada síncrona vs. streaming; tratamento de erros; exemplo reutilizável.

CONTRIBUTING.md explica o processo oficial de contribuição; os AGENTS.md (backend e frontend) descrevem convenções que todo PR precisa respeitar.

Ignorar essas páginas é a forma mais rápida de ter um PR rejeitado antes mesmo de ser revisado no mérito.

Setup do ambiente; estilo de código; testes obrigatórios; commits e PRs; convenções backend vs. frontend.

Pasta docs/rfcs tem as propostas técnicas formais; docs/plans tem planos de execução. Juntos, eles contam a história das decisões do projeto.

Propor mudança grande sem RFC é queimar a largada; ler RFCs antigos evita reabrir discussões já encerradas.

Template de RFC; status da proposta; relação com docs/plans; linkagem com PRs; open questions.

Leitura dos PRs mais recentes mergeados em middleware, guardrails, async e canais IM para entender o tamanho, forma e descrição esperados.

Imitar bons exemplos é o atalho para escrever PRs que passam na primeira revisão em vez da terceira.

Tamanho de PR; descrição rica; testes novos; changelog; checklist de self-review.

Técnica para garimpar issues do repositório que cabem em um PR pequeno e tem escopo claro — os "good first issues" explícitos e os implícitos.

Primeira contribuição importa mais pela entrega do que pela grandeza. Escolher uma issue do tamanho certo é metade do trabalho.

Labels oficiais; TODO.md; idade da issue; atividade no thread; sinalizar intenção de pegar.

Escolher um item do TODO.md, implementá-lo num fork, escrever descrição no padrão dos PRs recentes e abrir como draft PR no repositório oficial.

Draft PR é o entregável final desta trilha: prova que você lê, escreve, testa e conversa com o projeto upstream.

Fork; branch por feature; testes locais passando; descrição rica; link do draft PR como comprovante.