Implantando Seu Primeiro Agente Langgraph no TrueFoundry

Neste guia, mostraremos como implantar um Langgraph agente no TrueFoundry, uma plataforma projetada para simplificar a implantação de IA com experiência mínima em DevOps ou MLOps. O TrueFoundry automatiza o gerenciamento de infraestrutura, escalabilidade e monitoramento, permitindo que você se concentre em obter insights em vez de lidar com as complexidades da implantação. Com apenas alguns cliques, você pode transformar solicitações em linguagem natural em consultas SQL e gráficos dinâmicos, tornando a exploração de dados contínua e inteligente. Nenhuma consulta manual é necessária!

Se você quiser experimentar isso diretamente, visite a plataforma TrueFoundry e navegue até Live Demos e Langgraph-Streamlit: Demonstração ao vivo do nosso fluxo de trabalho do agente

Visão Geral da Arquitetura

Este projeto consiste em vários componentes chave trabalhando juntos:

Agente de Consulta

• Usa GPT-4o para compreensão de linguagem natural
• Gera consultas SQL apropriadas para ClickHouse
• Executa a consulta SQL em um banco de dados pré-configurado
• Retorna os dados em formato tabular como entrada para o agente de visualização

Agente de Visualização: Um segundo agente de IA que

• Determina o tipo de visualização mais apropriado com base nos dados
• Gera gráficos usando matplotlib/seaborn
• Gerencia a formatação e o estilo das visualizações

Backend FastAPI: API RESTful que

• Coordena entre agentes usando Langgraph
• Gerencia o processamento assíncrono de tarefas
• Serve imagens de gráficos e resultados

Frontend Streamlit: Interface de usuário que

• Oferece uma interface de consulta intuitiva
• Exibe o status de processamento em tempo real
• Mostra visualizações interativas

‍

Fluxo de Dados

1. O usuário envia uma consulta em linguagem natural através da interface do Streamlit
2. A consulta é processada pelo Agente SQL para gerar SQL
3. O SQL é executado no banco de dados ClickHouse
4. Os resultados são passados para o Agente de Gráficos
5. O Agente de Gráficos cria gráficos apropriados
6. Os resultados são exibidos na interface do Streamlit

‍Começando

Clonar o Repositório

Primeiro, navegue até o Exemplos de Primeiros Passos do TrueFoundry repositório e clone-o:

git clone <https://github.com/truefoundry/getting-started-examples.git>

Navegue até o Diretório do Agente de Plotagem

Mude para o diretório plot_agent:

cd getting-started-examples/plot_agent/langgraph_plot_agent

Configuração do Ambiente

Para criar e ativar um ambiente virtual:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Instalar dependências

pip install -r requirements.txt

Configuração do Ambiente

Copie o arquivo de ambiente de exemplo:

```bash
cp .env.example .env
```

Crie um .env arquivo com suas credenciais

# Truefoundry LLMGateway Configuration if using Truefoundry LLM Gateway for calling models
LLM_GATEWAY_BASE_URL=your_llm_gateway_base_url_here
LLM_GATEWAY_API_KEY=your_llm_gateway_api_key_here

# OPENAI API Configuration if not using Truefoundry LLM Gateway
OPENAI_API_KEY=<your_openai_api_key_here>

# ClickHouse Database Configuration
CLICKHOUSE_HOST=your_clickhouse_host_here
CLICKHOUSE_PORT=443
CLICKHOUSE_USER=your_clickhouse_user_here
CLICKHOUSE_PASSWORD=your_clickhouse_password_here
CLICKHOUSE_DATABASE=default

Observação: Ao usar o TrueFoundry LLM Gateway, o formato do ID do modelo deve ser provider-name/model-name (por exemplo, openai-main/gpt-4o). Certifique-se de que seu .env o arquivo contém as credenciais corretas do LLM Gateway, conforme mostrado na seção Configuração do Ambiente.

Para obter as credenciais do ClickHouse, crie uma conta em clickhouse, faça login e crie um serviço. Após clicar no serviço, você verá um botão de conexão no meio da barra lateral esquerda, no qual você pode clicar para ver as credenciais, conforme mostrado abaixo. Você pode criar um banco de dados enviando seus arquivos ou usar um pré-definido.

Implementação do Agente LangGraph

O projeto utiliza dois agentes LangGraph, o que também o torna uma referência prática útil ao avaliar AutoGen vs LangGraph para o design de fluxo de trabalho multiagente. Se você preferir usar apenas o OpenAI, então substitua:

model=OpenAIChat(
        id="openai-main/gpt-4o",  # Format: provider-name/model-name
        api_key=os.getenv("LLM_GATEWAY_API_KEY"),
        base_url=os.getenv("LLM_GATEWAY_BASE_URL")
    ),

Por:

model=OpenAIChat(
        id="gpt-4o",  # Specify model here
        api_key=os.getenv("OPENAI_API_KEY")
      ),

Veja como eles são configurados em uma configuração onde Langflow vs LangGraph frequentemente surge para escolhas de orquestração. 

class State(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]

tools_list = [execute_clickhouse_query, create_plot]

def tools_condition_modified(state):
    ans = tools_condition(state)
    human_messages_id = [m.id for m in state["messages"] if m.type == "human"]
    if ans == "tools":
        return "tools"
    else:
        return "__end__"

def create_agent():
    builder = StateGraph(State)

    llm = ChatOpenAI(
        model=os.getenv("MODEL_ID"), 
        api_key=os.getenv("LLM_GATEWAY_API_KEY"), 
        base_url=os.getenv("LLM_GATEWAY_BASE_URL"),
        streaming=True  # Enable streaming for the LLM
    )

    llm.bind_tools(tools_list)

    # Define nodes: these do the work
    builder.add_node("assistant", llm)
    builder.add_node("tools", ToolNode(tools_list))

    # Define edges: these determine how the control flow moves
    builder.add_edge(START, "assistant")
    builder.add_edge("tools", "assistant")
    builder.add_conditional_edges(
        "assistant",
        tools_condition_modified,
    )
    builder.add_edge("assistant", "__end__")

    agent = builder.compile()
    return agent

agent = create_agent()

Executando os Serviços

Iniciar servidor FastAPI:

python api.py

Iniciar UI do Streamlit (novo terminal):

streamlit run app.py

Implantação no TrueFoundry

Pré-requisitos

Instalar CLI do TrueFoundry:

pip install -U "truefoundry"

Fazer login no TrueFoundry:

tfy login --host "<https://app.truefoundry.com>"

Etapas de Implantação

1. Navegue até a seção de Implantações no TrueFoundry.

2. Clique em Serviço na parte inferior.
3. Selecione seu espaço de trabalho de cluster.
4. Você pode implantar a partir do seu laptop, GitHub ou Docker. Se estiver implantando a partir do seu laptop, certifique-se de ter concluído os pré-requisitos acima.
5. A plataforma TrueFoundry irá gerar um arquivo deploy.py e adicioná-lo ao seu projeto. Você precisará editar este arquivo para adicionar suas variáveis de ambiente. Encontre a seção 'env' no arquivo gerado e adicione suas credenciais:

# In the generated deploy.py file, locate the env section and add your variables:  
  env={
      # If using OPENAI  
      "OPENAI_API_KEY": "your_openai_api_key",  
      # If using LLM_GATEWAY
      "LLM_GATEWAY_API_KEY": "your_llm_gateway_api_key",
      "LLM_GATEWAY_BASE_URL": "your_llm_gateway_base_url",
      "CLICKHOUSE_HOST": "your_clickhouse_host",  
      "CLICKHOUSE_PORT": "443",  
      "CLICKHOUSE_USER": "your_user",  
      "CLICKHOUSE_PASSWORD": "your_password",  
      "CLICKHOUSE_DATABASE": "default",  
      "MODEL_ID": "gpt-4o"  
  },  

Certifique-se de substituir os valores de espaço reservado pelas suas credenciais reais. Sem essas variáveis de ambiente, sua aplicação não funcionará corretamente.

6. Execute o comando de implantação:

python deploy.py

Sua API de Fluxo de Trabalho SQL e Plot está agora implantada e em execução no TrueFoundry!

7. Para confirmar que tudo está funcionando, você pode enviar uma consulta de teste usando curl:

curl -X POST -H "Content-Type: application/json" \  
  -d '{"query": "Show me the cost trends by model over the last week"}' \  
  https://Langgraph-plot-agent-demo-8000.aws.demo.truefoundry.cloud/query  

Se tudo estiver configurado corretamente, você deverá receber uma resposta como:

{  
  "job_id": "123e4567-e89b-12d3-a456-426614174000",  
  "status": "processing",  
  "message": "Query is being processed. Check status with /status/{job_id}"  
}  

Monitoramento e Gerenciamento

Acesse o painel do TrueFoundry para:

• Monitorar o uso de recursos
• Visualizar logs da aplicação
• Dimensionar recursos conforme necessário
• Configurar regras de autoescalonamento

Verificar a saúde da aplicação:

• Saúde do backend: /health
• Documentação da API: /docs
• Métricas: /metrics

Exemplo de Uso:

1. Enviar uma Consulta via API:

curl -X POST "https://plot-agent-8000.your-workspace.truefoundry.cloud/query" \  
     -H "Content-Type: application/json" \  
     -d '{"query": "Show me the cost trends by model over the last week"}'  

2. Via UI do Streamlit:

• Navegue para o URL da UI
• Insira sua consulta no campo de texto
• Visualize o processamento e os resultados da consulta em tempo real

Endpoints da API

Enviar uma Consulta

curl -X POST http://localhost:8000/query \  
  -H "Content-Type: application/json" \  
  -d '{"query": "Show me the cost trends by model over the last week. Filter models that show a 0 cost."}'  

‍

Resposta

{  
  "job_id": "123e4567-e89b-12d3-a456-426614174000",  
  "status": "processing",  
  "message": "Query is being processed. Check status with /status/{job_id}"  
}  

‍

Verificar Status do Trabalho

curl -X GET http://localhost:8000/status/123e4567-e89b-12d3-a456-426614174000  

‍

Obter Imagem do Gráfico

curl -X GET http://localhost:8000/plot/123e4567-e89b-12d3-a456-426614174000 --output plot.png  

Implantando o Streamlit Separadamente

Para garantir a comunicação adequada entre FastAPI e Streamlit, você precisa implantar o Streamlit como um serviço separado na plataforma TrueFoundry.

1. Implante o frontend do Streamlit separadamente do FastAPI no TrueFoundry.
2. Configurar CORS no FastAPI:

from fastapi.middleware.cors import CORSMiddleware  

app.add_middleware(  
    CORSMiddleware,  
    allow_origins=["*"],  
    allow_credentials=True,  
    allow_methods=["*"],  
    allow_headers=["*"],  
)  

3. Definir uma Variável de Ambiente no Streamlit

Sua aplicação Streamlit deve usar uma variável de ambiente para apontar para o backend FastAPI: Na sua ambiente Streamlit configuração:

FASTAPI_ENDPOINT="https://langgraph-plot-agent-demo-8000.aws.demo.truefoundry.cloud"

Em seguida, modifique sua aplicação Streamlit para ler esta variável de ambiente:

import os

FASTAPI_ENDPOINT = os.getenv("FASTAPI_ENDPOINT", "http://localhost:8000")

Isso garante que o Streamlit referencie dinamicamente a instância correta do FastAPI.

        4. Use portas separadas

Se estiver implantando localmente ou se o TrueFoundry não lidar com conflitos de porta automaticamente, garanta que o FastAPI e o Streamlit rodem em portas separadas.

Exemplo:

FastAPI: https://langgraph-plot-agent-demo-8000.aws.demo.truefoundry.cloud

Streamlit: https://langgraph-streamlit-demo-8501.aws.demo.truefoundry.cloud

Para executar o Streamlit em uma porta diferente localmente:

streamlit run app.py --server.port 8501

Adicione rastreamentos ao seu agente

O rastreamento ajuda você a entender o que está acontecendo nos bastidores quando uma execução de agente é chamada. Você consegue compreender o caminho, as chamadas de ferramentas realizadas, o contexto utilizado e a latência ao executar seu agente usando a funcionalidade de rastreamento do Truefoundry, adicionando pouquíssimas linhas de código.

É necessário instalar o seguinte

 pip install traceloop-sdk

E em seguida, adicionar as variáveis de ambiente necessárias para habilitar o rastreamento

"TRACELOOP_BASE_URL": "<your_host_name>/api/otel" # "https://internal.devtest.truefoundry.tech/api/otel"
"TRACELOOP_HEADERS"="Authorization=Bearer%20<your_tfy_api_key>"

No seu código-fonte, onde você define seu agente, você só precisa destas linhas para habilitar o rastreamento

from traceloop.sdk import Traceloop
Traceloop.init(app_name="langraph")

Considerações Finais

Após implantar ambos os serviços, certifique-se de:

• Testar a conectividade da API do Streamlit para o FastAPI.
• Atualizar o do Streamlit .env arquivo com o endpoint correto do FastAPI.
• Confirmar se as configurações de CORS permitem requisições do Streamlit.

Isso garante que sua API de Fluxo de Trabalho SQL e Plot funcione corretamente em ambos os serviços.

‍

‍