Como Construir um Workflow Agentico com MCP no Floopy

Este tutorial explica como construir um workflow com agent loop real: um agente GPT-4o capaz de pesquisar na web para responder perguntas de pesquisa. Usaremos o Floopy como gateway de IA e o servidor MCP do Brave Search como provedor de ferramentas.

Ao final, voce tera um agent loop funcionando onde o modelo decide quando pesquisar, executa consultas, le os resultados e sintetiza uma resposta final — tudo pelo gateway do Floopy.

O Que Vamos Construir

Usuario: "Quais sao as principais diferencas entre os runtimes async do Rust, Tokio e async-std?"

Agente:
  Rodada 1 → chama web_search("Rust Tokio vs async-std comparacao 2025")
           ← resultado: [trechos de busca]
  Rodada 2 → chama web_search("status de manutencao async-std 2025")
           ← resultado: [trechos de busca]
  Rodada 3 → sintetiza resposta final com as informacoes coletadas
           → retorna resposta ao usuario

Pre-requisitos

• Uma conta Floopy no plano Pro
• Uma API key do Brave Search (nivel gratuito disponivel em brave.com/search/api)
• Node.js 18+ para testes

Passo 1: Armazene Seu Segredo

Nunca coloque chaves de API diretamente em arquivos de configuracao. Comece armazenando sua API key do Brave Search no Floopy Vault.

1. Abra o dashboard do Floopy
2. Va ate Configuracoes > Segredos
3. Clique em Adicionar Segredo
4. Nome: brave_search_api_key
5. Valor: sua API key do Brave Search
6. Clique em Salvar

O segredo agora esta criptografado em repouso e sera injetado em tempo de execucao. Ele nunca aparecera em logs ou respostas da API.

Passo 2: Crie uma Regra de Roteamento

Configuracoes de plugin de agent loop sao vinculadas a regras de roteamento.

1. Va ate Routing no dashboard
2. Clique em Nova Regra
3. Nomeie como agente-pesquisa
4. Defina o modelo padrao como gpt-4o
5. Deixe as demais configuracoes nos padroes por enquanto
6. Clique em Salvar

Passo 3: Escreva o Plugin YAML

O plugin YAML diz ao Floopy quais servidores MCP conectar e como executar o agent loop.

Crie um arquivo chamado agente-pesquisa.yaml:

version: "1"

mcp_servers:
  - id: brave_search
    url: "https://api.search.brave.com/mcp"
    auth:
      type: api_key
      header: "X-Subscription-Token"
      secret_ref: "secret.brave_search_api_key"
    tools:
      - web_search
    timeout_ms: 8000
    max_retries: 2

agent:
  max_rounds: 6
  stream_mode: final_only
  tool_call_parallel: false
  tool_cache_ttl_seconds: 300
  prompt_guard_on_tool_output: true

O que cada campo faz:

• secret_ref: "secret.brave_search_api_key" — referencia o segredo armazenado no Passo 1
• tools: [web_search] — expoe apenas essa ferramenta do servidor Brave
• max_rounds: 6 — permite ate 6 iteracoes de chamadas de ferramentas
• tool_cache_ttl_seconds: 300 — armazena em cache consultas identicas por 5 minutos
• prompt_guard_on_tool_output: true — analisa resultados de busca em busca de injecao de prompt

Passo 4: Vincule o Plugin a Sua Regra de Roteamento

1. Va ate Routing > agente-pesquisa no dashboard
2. Clique em MCP Plugin
3. Cole o conteudo do YAML
4. Clique em Salvar

O Floopy valida o schema do YAML e verifica se a referencia ao segredo existe. Se a validacao falhar, a mensagem de erro dira exatamente o que esta errado.

Passo 5: Teste no Playground

Antes de escrever codigo, teste a configuracao no Playground do Floopy.

1. Va ate Playground no dashboard
2. Selecione a regra de roteamento: agente-pesquisa
3. Digite esta mensagem:

Quais sao as principais diferencas de desempenho entre PostgreSQL e ClickHouse para cargas de trabalho analiticas?

4. Clique em Enviar

Observe a resposta sendo transmitida. No painel Trace a direita, voce vera cada chamada de ferramenta registrada em tempo real: a consulta de busca enviada, os resultados recebidos e em qual rodada do loop voce esta.

Se voce ver finish_reason: tool_calls seguido de resultados de ferramentas e depois um stop final, o loop esta funcionando corretamente.

Passo 6: Chame da Sua Aplicacao

Apos testar, chame a partir da sua aplicacao usando o SDK padrao do OpenAI:

import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://api.floopy.ai/v1",
  apiKey: process.env.FLOOPY_API_KEY,
  defaultHeaders: {
    "floopy-routing-rule": "agente-pesquisa",  // ativa sua regra de roteamento
  },
});

async function pesquisarPergunta(pergunta: string): Promise<string> {
  const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [
      {
        role: "system",
        content:
          "Voce e um assistente de pesquisa. Use busca na web para encontrar informacoes precisas e atualizadas antes de responder. Sempre cite suas fontes.",
      },
      {
        role: "user",
        content: pergunta,
      },
    ],
    stream: true,
  });

  let resultado = "";
  for await (const chunk of response) {
    const delta = chunk.choices[0]?.delta?.content;
    if (delta) {
      resultado += delta;
      process.stdout.write(delta);  // transmite para o console
    }
  }
  return resultado;
}

const resposta = await pesquisarPergunta(
  "Quais sao as principais diferencas entre os runtimes Tokio e async-std do Rust?"
);

A regra de roteamento ativa seu plugin MCP. Quando o GPT-4o decide chamar web_search, o Floopy cuida disso — o codigo da sua aplicacao nunca precisa saber que chamadas de ferramentas estao acontecendo.

Passo 7: Envie o Plugin Inline (Alternativa)

Se voce quiser usar o agent loop sem uma regra de roteamento — util para desenvolvimento ou personalizacao por requisicao — envie o plugin YAML inline via header de requisicao:

import { readFileSync } from "fs";

const pluginYaml = readFileSync("./agente-pesquisa.yaml", "utf-8");
const pluginBase64 = Buffer.from(pluginYaml).toString("base64");

const client = new OpenAI({
  baseURL: "https://api.floopy.ai/v1",
  apiKey: process.env.FLOOPY_API_KEY,
  defaultHeaders: {
    "floopy-mcp-plugin": pluginBase64,
  },
});

Passo 8: Monitore em Observabilidade

Cada sessao agentica e registrada completamente. Para inspecionar suas sessoes:

1. Va ate Observabilidade > Requisicoes no dashboard
2. Filtre por has_tool_calls: true
3. Clique em qualquer requisicao para expandir o trace completo

Para cada sessao voce vera:

Se uma sessao atingiu max_rounds, o log mostra finish_reason: max_rounds na ultima resposta.

Ajustando a Configuracao

O agente esta pesquisando vezes demais

Reduza max_rounds ou adicione um system prompt mais explicito:

Voce e um assistente de pesquisa. Pesquise no maximo duas vezes antes de sintetizar sua resposta.

As chamadas de ferramentas estao lentas

Diminua timeout_ms para falhar rapido em servidores lentos. Adicione max_retries: 1 para tentar uma vez antes de falhar.

Buscas identicas estao sendo repetidas

tool_cache_ttl_seconds: 300 armazena resultados em cache por 5 minutos. Se o agente enviar a mesma consulta duas vezes em uma sessao, ele acessa o cache em vez de chamar o servidor MCP novamente.

Voce quer ver chamadas de ferramentas intermediarias sendo transmitidas

Altere stream_mode de final_only para… na verdade, o streaming intermediario ainda nao esta disponivel — apenas a resposta final pode ser transmitida. O trace completo sempre esta disponivel em Observabilidade.

O Que Construir a Seguir

Com essa base, voce pode construir sistemas com agent loop mais complexos:

Agente multi-servidor: Adicione um servidor MCP de interpretador de codigo junto com a busca na web. O agente pode pesquisar solucoes e entao executar codigo para verifica-las.

Agente especializado: Substitua a busca na web por um servidor MCP de base de conhecimento interno da empresa. O agente recupera documentacao interna para responder perguntas de funcionarios.

Agente consciente de custos: Adicione chamadas estimate_cost no seu system prompt. O agente pode decidir se uma pergunta vale multiplas rodadas de busca ou deve ser respondida diretamente.

Documentacao de referencia completa: MCP Client · MCP Server · Tokens MCP