Crie um agente de pesquisa personalizado com o Langflow utilizando o watsonx Orchestrate ADK e o IBM Cloud

Langflow é um framework de código aberto em Python para construir agentes de IA e outras aplicações de IA. O Langflow foi originalmente construído sobre o LangChain, seu framework principal. LangGraph, outra plataforma da mesma família, também é utilizado para construir sistemas agênticos utilizando arquiteturas baseadas em grafos. O que diferencia o Langflow é sua interface intuitiva baseada em arrastar e soltar, na qual os usuários podem conectar componentes de agentes para criar fluxos de trabalho personalizados ou começar com os modelos predefinidos. Como alternativa a essa abordagem de pouco código ou no-code, os desenvolvedores podem criar componentes personalizados e incorporar fluxos de agentes passo a passo no código da aplicação existente utilizando a API Langflow. Neste tutorial do Langflow, exploramos como criar e implementar agentes por meio de:

1. Importação de fluxos de LangFlow agênticos como servidores MCP utilizando o IBM watsonx Orchestrate como Software como Serviço (SaaS) junto com a IBM Cloud.
2. Importação de fluxos básicos do LangFlow utilizando o IBM watsonx Orchestrate Agent Development Kit (ADK) localmente.

Ambas as abordagens correspondem a uma seção deste tutorial. Observe que você também pode acessar este tutorial no GitHub..

Vamos começar!

Este tutorial exige:

• A versão mais recente do Python instalada.
• Uma conta IBM Cloud para criar um watsonx.ai ID do projeto e chave de API. Há planos de serviço Lite e Gratuito disponíveis.
  • Você pode obter a ID do projeto a partir de seu projeto. Clique na guia Gerenciar. Em seguida, copie a ID do projeto da seção Detalhes da página Geral. Você precisa dessa ID para a parte do ADK deste tutorial.
• Uma conta do watsonx Orchestrate (pode ser uma conta de teste). Se você ainda não tem uma conta, clique aqui para cadastrar-se em uma avaliação gratuita de 30 dias. Confira na documentação instruções detalhadas sobre como obter acesso de teste no IBM Cloud.
• O IBM watsonx Orchestrate ADK instalado. Siga a documentação oficial aqui para configurar e instalar o ADK.
  • Observação: se você já instalou a edição watsonx Orchestrate Developer antes da versão 2.0 do ADK, primeiro remova todos os contêineres executando o orchestrate server reset antes da atualização. A edição watsonx Orchestrate Developer não depende mais de um mecanismo de contêiner externo. A falha na reinicialização antes da atualização pode fazer com que várias instalações da aplicação consumam recursos desnecessários do sistema e resultem em conflitos de portas.
• O CLI do IBM Cloud foi instalado. Os comandos de instalação para MacOS, Linux e Windows encontram-se no guia de iniciação.

Observe que sem esses requisitos não será possível reproduzir este tutorial.

No seu terminal, execute o seguinte comando. Você receberá um prompt para fazer login na sua conta IBM Cloud utilizando sua IBMid. Se você tiver várias contas, terá que selecionar uma.

Observação: Credenciais rejeitadas? Você pode ser um usuário federado. Efetue login novamente utilizando o sinalizador --sso para utilizar um ID de logon único corporativo ou corporativo. Para obter mais informações sobre como fazer registro com IDs federados, consulte a documentação. Em resumo, quando solicitado, permita que a URL seja aberta no navegador padrão e cole no terminal o código de uso único exibido.

Você saberá que sua entrada foi bem-sucedida quando vir uma saída semelhante.

Saída:

Nota: Se você perceber que a região não está correta, execute ibmcloud target -r seguido da região correta. Por exemplo, se o seu endpoint de serviço regional for  us-east , execute ibmcloud target -r us-east .

Para ver seus recursos de nuvem, execute ibmcloud resource groups . Esse comando deve resultar na recuperação dos seus grupos de recursos e produzir uma saída semelhante (os nomes e IDs dos seus recursos serão diferentes).

Saída:

Em seguida, direcione o recurso específico, executando ibmcloud target -g RESOURCE_GROUP . Neste exemplo, o comando seria ibmcloud target -g itz-wxo-69305f32086a49ee3736ff.

Esse resultado deve ser semelhante na saída.

Saída:

Com o IBM Cloud Code Engine, você pode rodar quase qualquer carga de trabalho conteinerizada sem gerenciar servidores ou infraestrutura. A plataforma aceita desde microsserviços e aplicativos web até trabalhos em lote e funções baseadas em eventos. Oferece também a criação integrada de imagens a partir de seu código-fonte. Como todas as cargas de trabalho compartilham o mesmo ambiente Kubernetes, elas se integram naturalmente. O Code Engine foi projetado para manter a infraestrutura fora do seu caminho para você se manter concentrado na construção de aplicações. A instalação da CLI do Code Engine é nossa próxima etapa. Execute o seguinte comando no seu terminal.

Saída:

Ótimo! Agora vamos direcionar um projeto dentro do Code Engine. Primeiro, exiba a lista de projetos executando ibmcloud ce project list.

Saída:

Um projeto do Code Engine agrupa entidades como aplicações, trabalhos e compilações. Serve como unidade para gerenciar recursos e controlar o acesso a essas entidades. Se você não tiver nenhum projeto ativo no Code Engine, execute ibmcloud ce project create --name PROJECT_NAME e substitua CE_PROJECT_NAME por qualquer nome de projeto de sua escolha (por exemplo, "code-engine-project").

Para direcionar o projeto específico, execute ibmcloud ce project select --name CE_PROJECT_NAME . Neste exemplo, o comando seria ibmcloud ce project select --name ce-itz-wxo-69305f32086a49ee3736ff.

Saída:

Observação: Se ocorrer um erro nesta etapa, verifique se você selecionou o ambiente correto com o ibmcloud target -c ACCOUNT_ID -r REGION_NAME -g RESOURCE_GROUP_NAME .

Para utilizar o Langflow enquanto utiliza a CLI do Code Engine, execute o comando a seguir.

Esse comando pode ser executado por vários minutos. Não interfira e permita a execução.

Saída:

À medida que o comando de configuração do Langflow for executado, podemos adicionar um ambiente para interagir com nossa máquina local e nossa solução SaaS hospedada.

Em outra janela de terminal, ative um ambiente virtual no diretório escolhido. Você pode alterar my-env para qualquer nome de ambiente de sua escolha.

Ative o ambiente virtual com o seguinte comando e substitua my-env pelo nome do seu ambiente, caso tenha usado outro:

MacOS/Linux:

Windows:

Agora, no seu navegador preferido, acesse sua lista de recursos IBM Cloud, expanda o menu suspenso de IA/Aprendizado de Máquina e selecione o recurso ativo wxO. O nome deve ser semelhante a “Watson Orchestrate-itz”, por exemplo, e então copie o URL encontrado na janela Credenciais. Mantenha esta página aberta em seu navegador, pois ela será necessária em breve. No comando a seguir, substitua YOUR_WXO_RESOURCE_URL pelo URL recuperado e execute o comando no ambiente virtual ativado no seu terminal.

Saída:

Quando a chave de API do wxO for solicitada, retorne à página de recursos aberta no navegador. Não insira a chave da API que está localizada acima do URL que você copiou. Em vez disso, clique no botão Iniciar o watsonx Orchestrate. Em seguida, clique no ícone circular com suas iniciais no canto superior direito da tela e abra as Configurações. Selecione a aba Detalhes da API e clique no botão Gerar chave da API. Em seguida, digite qualquer nome e descrição para sua chave de API e selecione "Desativar a chave vazada" na seção "Ação vazada". Mais importante ainda, selecione “Sim” na seção “Gerenciamento de sessão” para habilitar o gerenciamento de sessão para logins de CLI e clique em “Criar”. Sua chave de API deverá aparecer. Copie e cole a chave no terminal que você estava utilizando momentos atrás para atender à solicitação de inserção da chave da API wxO.

Saída:

Ótimo! O Langflow agora está ativo.

Para estabelecer um ambiente estável do Code Engine que não exclua nossa aplicação Langflow após um período de tempo limite fixo, abra seu navegador mais uma vez. Acesse a visão geral dos contêineres do IBM Cloud. Você deve ver seu projeto do Code Engine aparecer como foi criado mais recentemente. Abra o projeto. Em seguida, abra sua aplicação Langflow. Na aba Configuração, abra o componente Recursos e escalabilidade. A única alteração que precisamos fazer aqui é aumentar o número mínimo de instâncias de 0 para 1. Finalmente, clique no botão Implantar para aplicar essa revisão de configuração.

Após concluir esta etapa, clique no botão Testar aplicativo e depois no hiperlink URL do aplicativo. Essa ação abrirá nossa instância do IBM Cloud do Langflow.

Há muitas maneiras de criar um fluxo do Langflow. Use modelos construídos previamente ou crie os seus próprios a partir do zero. Neste tutorial vamos explorar o último. Para começar, clique em + Fluxo em branco. Este exemplo demonstra um fluxo que você pode construir, mas fique à vontade para explorar a infinidade de componentes e integrações incorporadas ao Langflow.

1. Adicione os seguintes nós de componentes integrados a partir do menu:

• Entrada de chat - Recebe a entrada do usuário do chat.

• Saída do Chat - Retorna a produção para o usuário no chat.

• Agente - Utiliza integração com um grande modelo de linguagem (LLM) para responder à entrada do usuário e pode ser conectado a várias ferramentas.²

• Ferramentas MCP - Conecta-se a um servidor do Protocolo de Contexto de Modelo (MCP) e expõe as funções do servidor MCP como ferramentas para os agentes usarem para responder à entrada.²

• IBM watsonx.ai - Dá acesso ao IBM watsonx.ai Modelos para geração de texto.³

• Pesquisa de notícias - Extrai conteúdo do Google Notícias e gera um DataFrame estruturado contendo o título, o link, a data de publicação e o resumo de cada artigo.⁴

• arXiv - Pesquisa no arXiv.org artigos relevantes e produção os resultados em formato DataFrame.⁵

  Finalmente, selecione + Novo componente personalizado na parte inferior do menu.

  Para facilitar a visualização, organize seu fluxo da seguinte maneira.

2. Conecte o componente de entrada de bate-papo ao campo “Entrada” do componente Agente.

3. Conecte o componente Saída de bate-papo ao campo “Resposta” do componente Agente.

4. No componente Agente, defina o “Provedor de Modelo” como “Personalizado” no menu suspenso. Dependendo da versão do Langflow que você está usando, poderá ver "Conectar outros modelos". Qualquer uma das opções é aceitável.

5.    No IBM watsonx.ai , selecione o endpoint da API do watsonx.ai apropriado para suas credenciais de APIs. Em seguida, cole o ID do projeto do watsonx.ai e a chave de API nos campos apropriados. Em seguida, selecione o nome do grande modelo de linguagem de sua escolha. Neste tutorial, podemos selecionar openai/gpt-oss-120b . Certifique-se de que o componente esteja definido como "Modelo de linguagem" em vez de "Resposta do modelo". Essa configuração é importante porque queremos utilizar esse modelo como modelo de linguagem para nosso agente. Portanto agora podemos conectar o IBM watsonx.ai. componente para o campo “Modelo de Linguagem” do componente Agente.

• Observação: Se preferir utilizar variáveis globais em vez de colar suas credenciais de API diretamente, clique no ícone do seu perfil no canto superior direito da tela e selecione Configurações. Na seção Variáveis Globais, adicione seu WATSONX_PROJECT_ID e WATSONX_APIKEY para a sua conexão com o watsonx.ai, que você gerou como pré-requisito para este tutorial. Quando voltar ao seu fluxo, você deverá ver um ícone de globo nos campos de texto "watsonx.ai Project ID" e "Chave de API". Clique no ícone e selecione a chave apropriada no menu suspenso.

6. Ative o Modo de ferramentas utilizando a opção correspondente ao arXiv, à Busca de Notícias e ao Componente Personalizado. Você verá esse botão aparecer no menu do cabeçalho clicando em qualquer lugar de cada um desses componentes. Com esse modo ativado, agora você pode conectar esses componentes ao campo “Ferramentas” do componente Agente. Os componentes arXiv e News Search estão configurados e prontos para serem usados. Podemos nos concentrar na configuração dos outros componentes agora.

7. No menu de cabeçalho do componente personalizado, selecione < > Code. Aqui, podemos personalizar o comportamento do componente editando o código Python que o define.⁶ Como exemplo simples, podemos criar uma ferramenta que retorne a data de hoje, conhecimento inacessível para um LLM. Substitua o código padrão pelo seguinte:

Vá em frente e salve suas alterações. Agora você deverá ver o componente refletindo seu novo nome, descrição e ícone.

8. O número de ferramentas que você dá ao seu agente depende de você. No entanto, lembre-se de não sobrecarregar seu agente com ferramentas demais, pois isso pode prejudicar o desempenho e a precisão. A última ferramenta que habilitaremos é um servidor MCP. Você pode se conectar a qualquer servidor de sua escolha. Neste tutorial, vamos nos conectar ao servidor Alpha Vantage MCP.⁷ O servidor oficial Alpha Vantage MCP facilita para LLMs e agentes a extração de dados de estoque passados e em tempo real utilizando o Model Context Protocol. Para conectar a este servidor, abra o menu suspenso “Servidor MCP” no componente Ferramentas MCP e clique em + Adicionar Servidor MCP. Na aba STDIO, dê qualquer nome para seu servidor, como "av_mcp", e cole o seguinte comando: uvx av-mcp YOUR_API_KEY . Para gerar uma chave de API gratuita do Alpha Vantage, acesse o site oficial do Alpha Vantage e cole no comando, substituindo o YOUR_API_KEY marcador de posição. Após adicionar o servidor, ative a opção " Modo de Ferramentas" no menu de cabeçalho do nó do componente. Você verá que uma vasta lista de ferramentas aparecerá como “Ações”. Esse resultado significa que sua conexão com o servidor MCP foi bem-sucedida. Agora você pode conectar esse componente final ao campo “Ferramentas” do componente Agente.

Bom trabalho! Seu fluxo está concluído e deve se assemelhar à captura de tela a seguir.

Para verificar se o pipeline de pesquisa está funcionando como o esperado, abra o Playground e converse com seu agente recém-criado! Faça perguntas ao agente que exijam a invocação de uma das ferramentas conectadas. Alguns valores de entrada de exemplo são:

• Simples:
  • “Qual é a data de hoje?”
  • “Encontre cinco artigos de pesquisa sobre computação quântica.”
• Moderado:
  • "Analise o preço das ações da IBM nos últimos 30 dias."
• Complexo:
  • "Existe alguma notícia recente que indique que as ações da IBM estão de alta ou de baixa?"

Você deverá ver o agente invocar suas ferramentas disponíveis e produzir a saída correta. Se você tiver alguma experiência de problemas nessa etapa, retorne ao seu fluxo e certifique-se de que suas credenciais estejam corretas e que você tenha seguido cada uma das etapas.

Uma maneira de conectar esse fluxo ao watsonx Orchestrate é como um servidor MCP. Clique no menu suspenso "Compartilhar " no canto superior direito e selecione "Servidor MCP". Clique na aba “JSON”. Você deverá ver um código semelhante a este exemplo:

Copie o URL em seu trecho JSON. Observe que ele será diferente do exemplo anterior. Volte ao seu terminal e cole o URL do servidor MCP no lugar do espaço reservado MCP_SERVER_URL. A execução deste comando a seguir na CLI do watsonx Orchestrate nos possibilita importar esse servidor MCP para a plataforma como um toolkit.

Saída:

Etapa 8. Crie um agente e teste as chamadas de ferramentas

No seu navegador, acesse o watsonx Orchestrate e crie um novo agente a partir do zero. Insira o nome e a descrição do seu agente. Depois de criado, abra a aba Conjunto de ferramentas e clique no botão Adicionar ferramenta. A partir daí, selecione para importar ferramentas de um servidor MCP. Na lista suspensa Selecione o servidor MCP, selecione o servidor que importamos, ative as ferramentas alternando a ativação e feche a janela. Em seguida, clique em Implementar. Após a implantação, você poderá conversar com seu agente na janela de Prévia do chat ou na interface de chat encontrada no menu recolhido da página.

Vamos fazer uma pergunta ao nosso corretor! Por exemplo, "Encontre cinco artigos de pesquisa sobre computação quântica."

Incrível! O chatbot agêntico está se comportando conforme o esperado, não apenas apresentando a resposta correta, como também invocando a ferramenta do arXiv apropriada. Fique à vontade para experimentar prompts diferentes.

Com essa abordagem, o Code Engine não é necessário. Essa abordagem configura um ambiente de desenvolvimento local utilizando o SDK do watsonx Orchestrate Developer Edition, uma versão leve do watsonx Orchestrate que funciona como um servidor de desenvolvimento local.

• Especificações da máquina:
  • 16 GB de RAM
  • 8 núcleos
  • 25 GB de espaço em disco

Antes de começar a construir localmente com o Langflow, instale a Developer Edition do wxO ADK. Observe que essa Developer Edition não foi necessária para a primeira abordagem deste tutorial.

1. No seu IDE preferido, configure seu ambiente. Crie uma pasta chamada wxo-langflow-agent para armazenar todos os agentes e todas as ferramentas. Esse projeto encontra-se no Github para ser utilizado como referência. A estrutura da pasta deve ser:

   wxo-langflow-agent/
   ├── .env
   ├── ferramentas/
   └── agentes/
   

2. Abra o terminal e ative um ambiente virtual. Altere  my-env  com qualquer nome de ambiente de sua escolha.

Ative o ambiente virtual com o seguinte comando e substitua my-env pelo nome do seu ambiente, caso tenha usado outro:

MacOS/Linux:

Windows:

3. No arquivo.env, defina as seguintes variáveis de ambiente. Para mais informações, consulte o guia de configuração.

4. Execute o comando a seguir para instalar o servidor watsonx Orchestrate Developer Edition. Não precisamos instalar o Langflow porque ele está incluído como parte do ADK Developer Edition. O sinalizador de comando --with-langflow possibilita a compatibilidade com o Langflow, extraindo as imagens de contêiner necessárias e realizando a configuração inicial para tornar o Langflow acessível localmente.

Esse comando pode ser executado por vários minutos se for a primeira vez que você ativa um servidor.

Solução de Problemas: Se você instalou o watsonx Orchestrate Developer Edition antes da versão 2.0 do ADK no passado e encontrou erros ao iniciar contêiner, execute:

O fim da saída deve ser semelhante ao exemplo a seguir.

Saída:

O editor do Langflow está disponível por meio do watsonx Orchestrate Developer Edition na porta 7861, conforme visto na saída anterior.

1. No seu navegador,  navegue até http://localhost:7861.
2. Construa seu fluxo. Podemos redirecionar o fluxo criado na primeira parte deste tutorial ou você pode criar o seu próprio. Você pode achar útil mais adiante neste tutorial dar ao fluxo um nome e uma descrição personalizados em vez dos padrão. Para isso, passe o mouse sobre o nome do fluxo na parte superior da tela e clique no ícone de lápis.

• Exemplo de nome de fluxo: Agente de pesquisa
• Descrição de fluxo de exemplo: acesso à pesquisa de notícias, arXiv, data de hoje e à API Alpha Vantage.

Podemos explorar duas opções para importar fluxos do Langflow para o nosso servidor local do watsonx Orchestrate:

a) Importe o fluxo como um servidor MCP local.

b) Importe o fluxo como JSON.

Essa etapa assemelha-se à etapa 7 da primeira metade deste tutorial, com algumas pequenas alterações. 

4. Na aba Toolset, clique no botão Adicionar ferramenta. Selecione "instância local" para adicionar nosso servidor MCP já importado, marque a caixa correspondente ao servidor MCP importado e clique em Adicionar ao agente.

5. Comece a conversar!

Como alternativa à importação de fluxos como servidores MCP, podemos utilizar o ADK para importar fluxos como arquivos JSON exportados.

1. Essa abordagem funciona melhor com fluxos simples. Para fins de demonstração, vamos utilizar este fluxo:

Exporte o fluxo para JSON clicando no botão Compartilhar e selecionando Exportar. Insira qualquer nome e descrição para a ferramenta/fluxo que você deseja. O nome da ferramenta deve conter somente caracteres alfanuméricos e sublinhados e não deve começar com um número ou sublinhado.

2. Adicione o arquivo JSON recém-exportado à pasta tools. 

3. Execute o comando a seguir para importar seu fluxo no watsonx Orchestrate.

4. Depois de importar o fluxo do Langflow como ferramenta, a próxima etapa é conectá-lo a um sistema de agentes. Faça essa etapa criando um novo agente na IU do watsonx Orchestrate ou copiando a seguinte definição de agente para um novo arquivoarxiv_agent.yml na pasta agents  .

Agora importe o agente simples executando:

5. Atualize o navegador da IU do watsonx Orchestrate em execução local para ver nossas alterações refletidas. No menu suspenso Agentes, selecione “Agente arXiv” e faça perguntas que exijam o uso da ferramenta arXiv!

Exemplo de prompt: "Encontre cinco artigos de pesquisa sobre computação quântica."

Saída:

Ótimo! O agente determinou que era necessário invocar a ferramenta arxiv para a consulta desse usuário. A saída da ferramenta é exibida no fluxo de raciocínio recolhido e na janela de bate-papo como resposta.

Este tutorial preparou você com as habilidades essenciais para aproveitar o Langflow e o watsonx Orchestrate para construir agentes robustos, escaláveis e prontos para empresas. Você aprendeu a importar fluxos agênticos do LangFlow como servidores MCP utilizando o watsonx Orchestrate como software como serviço (SaaS) junto com o IBM Cloud. Além disso, agora você está familiarizado com a importação de fluxos básicos do LangFlow utilizando o IBM watsonx Orchestrate Agent Development Kit (ADK) localmente. Seguindo as instruções passo a passo, você aprendeu a projetar, desenvolver e implementar agentes que invocam ferramentas personalizadas e criadas previamente para resolver consultas de usuários. Com a interface visual intuitiva do Langflow, você criou fluxos de trabalho complexos e o watsonx Orchestrate capacitou você a gerenciar e escalar esses agentes de forma eficiente. Como próxima etapa, aplique o conhecimento adquirido neste tutorial trabalhando em um caso de uso do mundo real. Escolha um problema ou processo de negócios específico na sua organização que poderia se beneficiar da automação e crie uma solução baseada no Langflow e no watsonx Orchestrate para lidar com ele. Essa experiência prática solidificará sua compreensão e ajudará a identificar áreas para melhoria ou exploração adicionais.

Se encontrar problemas ou tiver dúvidas, consulte a documentação. Os problemas mais comuns são abordados no guia de resolução de problemas. Você pode também revisar os problemas do GitHub para ver se outras pessoas enfrentaram problemas semelhantes.