Como Implantar um fluxo de trabalho MultiAgente usando CrewAI no TrueFoundry

Neste guia, mostraremos como implantar um CrewAI agente no TrueFoundry, uma plataforma projetada para simplificar a implantaçã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 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 CrewAI-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 adequado com base nos 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 CrewAI
• 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 através do Streamlit.

• O Agente de Consulta usa CrewAI 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 Gráficos CrewAI:

cd getting-started-examples/plot_agent/crewai_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 pip install -r requirements.txt

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
CREWAI_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 CrewAI

@CrewBase
class CrewaiPlotAgent():
	"""CrewaiPlotAgent crew"""

	# Learn more about YAML configuration files here:
	# Agents: https://docs.crewai.com/concepts/agents#yaml-configuration-recommended
	# Tasks: https://docs.crewai.com/concepts/tasks#yaml-configuration-recommended
	agents_config = 'config/agents.yaml'
	tasks_config = 'config/tasks.yaml'

	# def process_output(self, output):
	# 	# Modify output after the crew finishes
	# 	output.raw += "\nProcessed after kickoff."
	# 	print("Output", output ,"sdfsdfsdfsd")
	# 	return output

	# If you would like to add tools to your agents, you can learn more about it here:
	# https://docs.crewai.com/concepts/agents#agent-tools
	@agent
	def sql_writer(self) -> Agent:
		return Agent(
			config=self.agents_config['sql_writer'],
			verbose=True,
			tools=[ClickHouseTool()]
		)

	@agent
	def plot_writer(self) -> Agent:
		return Agent(
			config=self.agents_config['plot_writer'],
			verbose=True,
			tools=[PlotTools()],
			pydantic_output=PlotResult,
		)

	# To learn more about structured task outputs, 
	# task dependencies, and task callbacks, check out the documentation:
	# https://docs.crewai.com/concepts/tasks#overview-of-a-task
	@task
	def sql_task(self) -> Task:
		return Task(
			config=self.tasks_config['sql_task'],
		)

	@task
	def plot_task(self) -> Task:
		return Task(
			config=self.tasks_config['plot_task'],
			# callback=self.process_output,
			allow_code_execution=True,
			output_pydantic=PlotResult,
			# output_file='plot.png'
		)

	@crew
	def crew(self) -> Crew:
		"""Creates the CrewaiPlotAgent crew"""
		# To learn how to add knowledge sources to your crew, check out the documentation:
		# https://docs.crewai.com/concepts/knowledge#what-is-knowledge

		return Crew(
			agents=self.agents, # Automatically created by the @agent decorator
			tasks=self.tasks, # Automatically created by the @task decorator
			process=Process.sequential,
			verbose=True,
			# output_pydantic=True,
			# process=Process.hierarchical, # In case you wanna use that instead https://docs.crewai.com/how-to/Hierarchical/
		)
	

Os decoradores @Crewbase, @agent, @task etc. servem para habilitar o rastreamento no TrueFoundry, conforme mencionado em detalhes posteriormente.

Executando os Serviços

Iniciar Fluxo de Trabalho CrewAI

crewai 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 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 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 arquivo deploy.py gerado e edite a seção env :

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",
    "CREWAI_VERBOSE": "true"
},

Substitua os espaços reservados pelas suas credenciais e configurações de ambiente.

Testando a Implantação

Enviar 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://crewai-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.
• Atualize o .env arquivo com o endpoint do FastAPI.
• Confirme se as configurações de CORS permitem solicitaçõ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
• Verificando a 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 de agente é chamada. Você consegue compreender o caminho, as chamadas de ferramentas realizadas, o contexto utilizado e a latência quando executa 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 adicione 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
from traceloop.sdk.decorators import workflow, agent, task
Traceloop.init(app_name="crew-ai")

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 estas etapas, seu fluxo de trabalho de agente CrewAI está agora implantado com sucesso no TrueFoundry!

‍