Implantando Seu Agente Agno na TrueFoundry

Neste guia, mostraremos como implementar um Agno agente no TrueFoundry, uma plataforma projetada para simplificar a implementação de IA com mínima experiência em DevOps ou MLOps. O TrueFoundry automatiza o gerenciamento de infraestrutura, escalabilidade e monitoramento, permitindo que você se concentre na obtenção de insights em vez de lidar com as complexidades da implementaçã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 inteligente e sem interrupções. Nenhuma consulta manual é necessária!

Se você quiser experimentar isso diretamente, visite a plataforma TrueFoundry e navegue até Live Demos e agno-Streamlit: Demonstração ao vivo do nosso fluxo de trabalho de 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 o 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, dados os dados
• Gera gráficos usando matplotlib/seaborn
• Lida com a formatação e o estilo das visualizações

Backend FastAPI: API RESTful que

• Coordena entre agentes usando agno
• 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

O usuário envia uma consulta em linguagem natural via Streamlit.

• O Agente de Consulta usa agno com GPT-4o para gerar consultas SQL para o ClickHouse
• Executa a consulta SQL no banco de dados ClickHouse
• Os resultados são retornados em formato tabular como entrada para o Agente de Visualização
• O Agente de Visualização gera visualizações e retorna imagens para exibição

Primeiros Passos

Clone o Repositório

Primeiro, navegue até o TrueFoundry Getting Started Examples repositório e clone-o:

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

Navegue até o Diretório do Agente de Plotagem agno:

cd getting-started-examples/plot_agent/agno_plot_agent

Configuração do Ambiente

Crie e ative um ambiente virtual:

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

Instale as dependências:

pip install uv
uv install

Configure as Variáveis de Ambiente

Crie um .env arquivo:

# 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_HOST=your_clickhouse_host
CLICKHOUSE_PORT=443
CLICKHOUSE_USER=your_user
CLICKHOUSE_PASSWORD=your_password
CLICKHOUSE_DATABASE=default
agno_VERBOSE=true

‍
Nota: 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 arquivo contenha 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, que 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 Agno

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from plot_tools import PlotTools
from query_tools import QueryTools
import os
# Query Agent for SQL generation - Using TrueFoundry LLM Gateway
sql_agent: Agent = Agent(
                        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")
                        ),
                        description="",
                        instructions=[],
                        tools=[ClickHouseTools()],
                        show_tool_calls=True,
                        markdown=True,
                        response_model=SQLQueryResult,
                        structured_outputs=True,
                        )
# Visualization Agent - Using TrueFoundry LLM Gateway
plot_agent: Agent = Agent(
                          model=OpenAIChat(
                              id="openai-main/gpt-4o",
                              api_key=os.getenv("LLM_GATEWAY_API_KEY"),
                              base_url=os.getenv("LLM_GATEWAY_BASE_URL")
                          ),
                          description="",
                          instructions=[],
                          tools=[PlotTools()],
                          markdown=True,
                          response_model=VisualizationRequest,
                          structured_outputs=True,
                          )

Executando os Serviços

Iniciar Fluxo de trabalho agno

agno run

Iniciar Backend FastAPI:

python api.py

Iniciar UI Streamlit (novo terminal):

streamlit run app.py

Implantação no TrueFoundry

Pré-requisitos

Instalar CLI 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 do cluster.
4. Você pode implantar do seu laptop, GitHub ou Docker. Se for implantar do seu laptop, certifique-se de ter concluído os pré-requisitos acima.
5. A plataforma TrueFoundry gerará um arquivo deploy.py e o adicionará 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:
6. Use o gerado deploy.py e edite a env seção:

env={
    "OPENAI_API_KEY": "your_openai_api_key",
    "CLICKHOUSE_HOST": "your_clickhouse_host",
    "CLICKHOUSE_PORT": "443",
    "CLICKHOUSE_USER": "your_user",
    "CLICKHOUSE_PASSWORD": "your_password",
    "CLICKHOUSE_DATABASE": "default",
    "AGNO_VERBOSE": "true"
},

Testando a Implantação

Envie uma consulta de teste:

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

Exemplo de resposta bem-sucedida:

{
  "job_id": "1234-abcd-5678-efgh"
}

Endpoints da API

• Enviar uma Consulta:

curl -X POST <http://localhost:8000/query> -H "Content-Type: application/json" -d '{"query": "Your query here."}'

• Verificar Status da Consulta:

curl -X GET <http://localhost:8000/status/{job_id}>

• Recuperar Imagem do Gráfico:

curl -X GET <http://localhost:8000/plot/{job_id}> > plot.png

Frontend e CORS

Configurar CORS no FastAPI:

from fastapi.middleware.cors import CORSMiddleware

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

Definir Variável de Ambiente no Streamlit:

import os

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

Notas Pós-implantação

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

Monitore e gerencie sua implantação através do TrueFoundry por meio de:

• Visualização de logs
• Monitoramento do uso de recursos
• Definição de regras de autoescalonamento
• Verificação da saúde do backend (/health), documentação da API (/docs), e métricas em /metrics

Adicione rastreamentos ao seu agente

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

Você precisa instalar o seguinte

 pip install traceloop-sdk

E então 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>"

Na sua base de código, onde você define seu agente, você só precisa destas linhas para habilitar o rastreamento

from traceloop.sdk import Traceloop
from traceloop.sdk.decorators import workflow, agent, task
Traceloop.init(app_name="agno")

Em seguida, adicione o decorador ao agente e aos fluxos de trabalho, como o seguinte

@agent(name="sql_and_plot_workflow")
@workflow(name="plotting workflow")
@task(name="execute sql query")

Com estes passos, o fluxo de trabalho do seu agente agno está agora implantado com sucesso na TrueFoundry!