Integração de conhecimento em PDFs com um agente de IA utilizando AGNO

Introdução

No mundo da inteligência artificial, a capacidade de recuperar informações de maneira eficaz é crucial. Neste artigo, vamos explorar como construir um sistema de Recuperação-Augmentada de Geração (RAG) simples utilizando a biblioteca AGNO, a API da OpenAI e um banco de dados vetorial LanceDB. Vamos focar na extração de informações a partir de documentos PDF, permitindo que um agente de IA responda a perguntas baseadas no conteúdo desses documentos.

O que é RAG?

Recuperação-Augmentada de Geração (RAG) é um modelo que combina técnicas de recuperação de informações e geração de texto. Ele permite que um agente de IA busque dados relevantes em fontes externas e os utilize para gerar respostas mais precisas e informativas. No nosso caso, utilizaremos um PDF como fonte de conhecimento.

Pré-requisitos

Antes de começarmos, precisamos instalar algumas bibliotecas essenciais. Execute o seguinte comando para instalar as dependências necessárias:

pip install agno openai lancedb pandas pypdf

Configurando o Ambiente

Primeiro, vamos importar as bibliotecas necessárias e configurar a chave da API da OpenAI:

import os
from agno.agent import Agent
from agno.embedder.openai import OpenAIEmbedder
from agno.knowledge.pdf import PDFKnowledgeBase
from agno.models.openai import OpenAIChat
from agno.vectordb.lancedb import LanceDb
os.environ["OPENAI_API_KEY"] = "sua chave_api_openai"

Certifique-se de substituir `sua chave_api_openai` pela sua chave real da API da OpenAI.

Criando a Base de Conhecimento

Agora, vamos criar uma base de conhecimento a partir de um documento PDF. Para isso, utilizaremos a classe `PDFKnowledgeBase` e configuraremos um banco de dados vetorial com o LanceDB:

knowledge_base = PDFKnowledgeBase(
 path="sample_data/livro_da_minha_vida.pdf",
 vector_db=LanceDb(
 table_name="content",
 uri="tmp/lancedb",
 embedder=OpenAIEmbedder(id="text-embedding-3-small")
 ),
)

# Carrega o conteúdo do PDF na base de conhecimento
knowledge_base.load()

Neste exemplo, o caminho para o PDF é `sample_data/livro_da_minha_vida.pdf`. Você pode substituir isso pelo caminho do seu próprio arquivo PDF.

Criando o Agente

Com a base de conhecimento carregada, agora podemos criar um agente que utilizará este conhecimento para responder perguntas:

agent = Agent(
 model=OpenAIChat(id="gpt-4o"),
 knowledge=knowledge_base,
 add_references=True,
 search_knowledge=False,
 markdown=True
)

Aqui, estamos utilizando o modelo GPT-4 da OpenAI e configurando o agente para adicionar referências e usar a formatação Markdown nas respostas.

Fazendo Perguntas ao Agente

Agora que tudo está configurado, podemos fazer perguntas ao nosso agente. Vamos perguntar sobre o dia do nosso nascimento:

agent.print_response(
 "Qual é o dia do meu nascimento?", stream=True
)

Esta linha de código enviará a pergunta ao agente, que utilizará o conhecimento extraído do PDF para gerar uma resposta.

Boas Práticas

1. Gerenciamento de Erros: Sempre implemente tratamentos de exceção para lidar com possíveis erros ao carregar documentos ou fazer chamadas à API.
2. Documentação: Mantenha uma documentação clara do seu código e das bibliotecas utilizadas.
3. Segurança: Nunca exponha sua chave API. Utilize variáveis de ambiente ou arquivos de configuração seguros.

Conclusão

Neste artigo, construímos um sistema simples de RAG utilizando a biblioteca AGNO e a API da OpenAI. Essa abordagem permite que você crie agentes mais inteligentes e informativos, capazes de responder a perguntas baseadas em documentos PDF.

Experimente adaptá-lo para suas próprias necessidades e explore as possibilidades que a integração de IA pode oferecer!

Exemplos de Código

pip install agno openai lancedb pandas pypdf

python
import os

from agno.agent import Agent
from agno.embedder.openai import OpenAIEmbedder
from agno.knowledge.pdf import PDFKnowledgeBase
from agno.models.openai import OpenAIChat
from agno.vectordb.lancedb import LanceDb

os.environ["OPENAI_API_KEY"] = "sua chave_api_openai"
knowledge_base = PDFKnowledgeBase(
 path="sample_data/livro_da_minha_vida.pdf",
 vector_db=LanceDb(
 table_name="content",
 uri="tmp/lancedb",
 embedder=OpenAIEmbedder(id="text-embedding-3-small")
 ),
)
knowledge_base.load()
agent = Agent(
 model=OpenAIChat(id="gpt-4o"),
 knowledge=knowledge_base,
 add_references=True,
 search_knowledge=False,
 markdown=True
)
agent.print_response(
 "Qual é o dia do meu nascimento?", stream=True
)

No mundo em constante evolução da inteligência artificial, criar agentes personalizados que possam interagir de forma eficaz com os usuários é uma tarefa cada vez mais relevante. Neste artigo, vamos explorar como criar ferramentas (tools) para seu agente de IA utilizando a biblioteca CrewAI. Veremos que, com alguns passos simples, é possível adicionar funcionalidades personalizadas ao seu agente.

O que é o CrewAI?

CrewAI é uma biblioteca que facilita a criação e gestão de agentes de IA. Com ela, você pode definir o papel do agente, suas responsabilidades e até mesmo construir ferramentas que o agente pode usar para interagir com os usuários de maneira mais eficaz.

Passo a Passo para Criar uma Ferramenta

Passo 1: Instalação da Biblioteca

Primeiramente, precisamos instalar a biblioteca CrewAI. Isso pode ser feito facilmente utilizando o pip:

pip install crewai

Passo 2: Criar uma Ferramenta Personalizada

Vamos começar criando uma ferramenta simples que retornará uma saudação personalizada. Para isso, utilizaremos o decorador @tool fornecido pela biblioteca CrewAI:

from crewai.tools import tool

@tool
def saudacao(nome: str) -> str:
    """Retorna uma saudação personalizada."""
    return f"Olá, {nome}! Bem-vindo à CrewAI!"

Neste exemplo, a função saudacao recebe um nome como parâmetro e retorna uma saudação formatada.

Passo 3: Criar um Agente

Agora que temos nossa ferramenta, podemos criar um agente que utilizará essa ferramenta. O agente pode ser definido da seguinte maneira:

from crewai import Agent

meu_agente = Agent(
    role="Agente de Boas-Vindas",
    goal="Cumprimentar o usuário de forma personalizada",
    backstory="Este agente adora receber novos usuários e deixá-los confortáveis.",
    tools=[saudacao]
)

Explicação dos Parâmetros

• role: Define o papel do agente. Neste caso, é um agente de boas-vindas.
• goal: O objetivo do agente. Aqui, o agente tem a tarefa de cumprimentar o usuário.
• backstory: Um pequeno contexto sobre a personalidade do agente, que pode ajudar na interação.
• tools: A lista de ferramentas que o agente pode utilizar, incluindo a nossa função saudacao.

Passo 4: Criar uma Tarefa

Em seguida, vamos criar uma tarefa que o agente deve realizar. Essa tarefa descreverá o que o agente deve fazer:

from crewai import Task

tarefa_cumprimentar = Task(
    description="Cumprimente o usuário chamado João utilizando sua ferramenta.",
    expected_output="Uma saudação personalizada para João.",
    agent=meu_agente
)

A tarefa inclui uma descrição e a saída esperada, que neste caso é a saudação personalizada para o usuário chamado João.

Passo 5: Criar e Executar a Crew

Finalmente, podemos criar uma equipe (Crew) que inclui nosso agente e a tarefa que ele deve realizar:

from crewai import Crew

equipe = Crew(
    agents=[meu_agente],
    tasks=[tarefa_cumprimentar]
)

Agora, vamos executar a equipe com o input necessário:

resultado = equipe.kickoff(inputs={"nome": "João"})
print(resultado)

Isso resultará na execução da tarefa e, como saída, teremos a saudação personalizada para João.

Conclusão

Neste artigo, mostramos como é simples criar uma ferramenta personalizada para um agente de IA utilizando a biblioteca CrewAI. Com apenas algumas linhas de código, você pode aumentar a interatividade e a personalização do seu agente, tornando a experiência do usuário muito mais agradável.

Boas Práticas

• Sempre documente suas ferramentas e agentes para facilitar o entendimento futuro.
• Mantenha suas funções de ferramenta simples e focadas em uma única responsabilidade.
• Teste suas implementações para garantir que o agente se comporte conforme o esperado.

Dicas

• Explore outras funcionalidades da biblioteca CrewAI para expandir as capacidades do seu agente.
• Considere criar múltiplas ferramentas e atribuí-las a diferentes agentes para interações mais ricas.

Esses passos simples podem levar você a criar agentes de IA altamente eficazes e personalizados utilizando o CrewAI!

Exemplos de Código

pip install crewai

from crewai import Agent, Task, Crew
from crewai.tools import tool

@tool
def saudacao(nome: str) -> str:
    """Retorna uma saudação personalizada."""
    return f"Olá, {nome}! Bem-vindo à CrewAI!"


meu_agente = Agent(
    role="Agente de Boas-Vindas",
    goal="Cumprimentar o usuário de forma personalizada",
    backstory="Este agente adora receber novos usuários e deixá-los confortáveis.",
    tools=[saudacao]
)

tarefa_cumprimentar = Task(
    description="Cumprimente o usuário chamado João utilizando sua ferramenta.",
    expected_output="Uma saudação personalizada para João.",
    agent=meu_agente
)

equipe = Crew(
    agents=[meu_agente],
    tasks=[tarefa_cumprimentar]
)


resultado = equipe.kickoff(inputs={"nome": "João"})
print(resultado)

Sinta-se à vontade para experimentar o CrewAI e personalizar seus agentes da maneira que preferir!

Neste artigo, vamos explorar como conectar um agente de IA utilizando o Multi-Command Protocol (MCP) com a biblioteca CrewAI. Vamos usar um exemplo prático que interage com o Airbnb, permitindo ao agente buscar e analisar informações sobre acomodações.

Pré-requisitos

Antes de começarmos, você precisará ter o Python instalado em seu sistema, além de algumas bibliotecas que utilizaremos em nosso projeto.

Configurando o Ambiente

Primeiro, crie um ambiente virtual para isolar suas dependências:

python -m venv venv
source venv/bin/activate  # Para Linux/Mac
venv\Scripts\activate  # Para Windows

Agora, instale as bibliotecas necessárias:

pip install crewai "crewai-tools[mcp]"

Estrutura do Código

Vamos analisar o código em partes, explicando o que cada seção faz.

1. Importando Bibliotecas e Configurando a Chave API

from crewai import Agent, Task, Crew
from crewai_tools import MCPServerAdapter
from mcp import StdioServerParameters
import os

os.environ["OPENAI_API_KEY"] = "SUA_CHAVE_API_OPENAI"

Nesta seção, estamos importando as bibliotecas necessárias e configurando a chave API da OpenAI. Lembre-se de substituir SUA_CHAVE_API_OPENAI pela sua chave real.

2. Configuração dos Parâmetros do Servidor MCP

server_params = StdioServerParameters(
    command="npx",
    args=["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"],
)

Aqui, estamos configurando os parâmetros do servidor MCP. Utilizamos o comando npx para executar o servidor MCP do Airbnb, que irá buscar as informações de acomodações. O argumento --ignore-robots-txt permite que o agente ignore as restrições do arquivo robots.txt do site.

3. Criando o Agente

with MCPServerAdapter(server_params) as tools:
    agent = Agent(
        role="Especialista em Busca do Airbnb",
        goal="Buscar e analisar informações de acomodações no Airbnb",
        backstory="Um especialista em encontrar as melhores opções de acomodações no Airbnb",
        tools=tools,
        verbose=True,
    )

Neste trecho, estamos criando o agente que irá interagir com o MCP. O agente é configurado com um papel, um objetivo e uma história de fundo, o que ajuda a definir seu comportamento durante as interações.

4. Criando uma Tarefa

task = Task(
    description="Buscar informações de acomodações no Airbnb no capão dedondo com preço máximo de 100 reais por noite",
    expected_output="Lista de acomodações disponíveis com detalhes",
    agent=agent,
)

Aqui, criamos uma tarefa para o agente. A descrição detalha o que o agente deve fazer, e a saída esperada informa como o resultado deve ser formatado.

5. Criando e Executando a Crew

crew = Crew(
      agents=[agent],
      tasks=[task],
      verbose=True,
  )
result = crew.kickoff()
print(result)

Finalmente, criamos uma Crew que contém o agente e a tarefa. O método kickoff() inicia a execução do agente, e o resultado é impresso na tela.

Conclusão

Neste artigo, cobrimos como conectar um agente de IA via MCP utilizando a biblioteca CrewAI. Com o exemplo prático, você pode adaptar e expandir esta funcionalidade para atender a diferentes necessidades. A interação com o Airbnb é apenas uma das muitas possibilidades que você pode explorar com esse setup.

Com isso, você está pronto para começar a trabalhar com agentes de IA e explorar o potencial do MCP com CrewAI!

Códigos de Exemplo

Exemplo 1

pip install crewai "crewai-tools[mcp]"

Exemplo 2

from crewai import Agent, Task, Crew
from crewai_tools import MCPServerAdapter
from mcp import StdioServerParameters
import os

os.environ["OPENAI_API_KEY"] = "SUA_CHAVE_API_OPENAI"

server_params = StdioServerParameters(
    command="npx",
    args=["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"],
)

with MCPServerAdapter(server_params) as tools:
    agent = Agent(
        role="Especialista em Busca do Airbnb",
        goal="Buscar e analisar informações de acomodações no Airbnb",
        backstory="Um especialista em encontrar as melhores opções de acomodações no Airbnb",
        tools=tools,
        verbose=True,
    )

    task = Task(
            description="Buscar informações de acomodações no Airbnb no capão dedondo com preço máximo de 100 reais por noite",
            expected_output="Lista de acomodações disponíveis com detalhes",
            agent=agent,
        )
    
    crew = Crew(
            agents=[agent],
            tasks=[task],
            verbose=True,
        )
    result = crew.kickoff()
    print(result)

Este artigo foi escrito para ajudar desenvolvedores a entender a integração de agentes de IA utilizando o CrewAI e MCP.

Este guia explica como desenvolver uma aplicação usando o padrão Model-Controller-Presenter (MCP) integrado às poderosas bibliotecas FastMCP e LangChain em Python.

📋 Pré-requisitos

Antes de começar, certifique-se de instalar todas as dependências necessárias:

Criando um Ambiente Virtual

Linux:

python3 -m venv .venv
source .venv/bin/activate

Windows:

python -m venv .venv
.venv\Scripts\activate

Instalando Dependências

pip install fastmcp langchain langchain-community langchain-openai

📂 Organização do Projeto

O projeto será estruturado em dois arquivos principais:

• server.py: Responsável por configurar e executar o servidor MCP.
• client.py: Realiza requisições ao servidor utilizando LangChain com um modelo de linguagem OpenAI.

🔧 Desenvolvendo o Servidor MCP (server.py)

O servidor MCP é responsável por gerenciar funções específicas expostas como ferramentas (tools).

from fastmcp import FastMCP

# Criação do servidor MCP
server = FastMCP("Servidor de Teste")
server.dependencies = []  # Nenhuma dependência externa inicializada

# Define uma ferramenta para somar dois números inteiros
@server.tool()
def somar(a: int, b: int) -> int:
    """Soma dois números inteiros. Exemplo de entrada: '8 10'"""
    if not isinstance(a, int) or not isinstance(b, int):
        raise ValueError("Os parâmetros devem ser números inteiros.")
    return a + b

if __name__ == "__main__":
    server.run()

Explicação Detalhada

• FastMCP: Classe utilizada para criar um servidor MCP.
• @server.tool(): Decorador que transforma funções Python em ferramentas acessíveis remotamente.
• Validações internas garantem a integridade dos dados.

💻 Desenvolvendo o Cliente com LangChain (client.py)

O cliente interage com o servidor MCP e usa o modelo de linguagem OpenAI através do LangChain para processamento inteligente das solicitações.

import os
import subprocess
from langchain.agents import initialize_agent, AgentType
from langchain.chat_models import ChatOpenAI
from langchain.tools import Tool

# Configure a chave da API da OpenAI
os.environ["OPENAI_API_KEY"] = "sua-chave-api-aqui"

# Função que interage com o servidor MCP através de subprocessos
def chamar_mcp_ferramenta(input_str: str) -> str:
    process = subprocess.Popen(
        ['python', 'server.py'],
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True
    )
    stdout, stderr = process.communicate(input_str)
    return stdout.strip()

# Definição das ferramentas que o LangChain pode acessar
tools = [
    Tool(
        name="Somar",
        func=lambda x: chamar_mcp_ferramenta(f"somar {x}"),
        description="Soma dois números inteiros. Exemplo: '8 10'"
    )
]

# Inicialização do modelo de linguagem e do agente LangChain
llm = ChatOpenAI(temperature=0)
agent = initialize_agent(
    tools,
    llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

# Exemplo prático do agente respondendo a uma pergunta
if __name__ == "__main__":
    pergunta = "Qual é a soma de 10 e 4?"
    resposta = agent.run(pergunta)
    print("\n🤖 Resposta:", resposta)

Explicação Detalhada

• Usa subprocess para comunicação inter-processos (IPC) com o servidor MCP.
• Define ferramentas do LangChain que encapsulam chamadas ao servidor.
• O modelo ChatOpenAI responde perguntas utilizando processamento de linguagem natural.

🚀 Executando a Aplicação

Siga estes passos para executar o projeto:

1. Inicie o servidor MCP:

fastmcp install .\server.py
fastmcp dev .\server.py

2. Em outro terminal, rode o cliente LangChain:

python3 .\client.py

Você verá o agente realizar chamadas ao servidor MCP e retornar resultados processados pelo modelo de linguagem OpenAI.

📖 Por que usar MCP e LangChain?

• Estrutura organizada e clara: Separação eficiente entre camadas do projeto.
• Reutilização facilitada: Ferramentas definidas no servidor podem ser reutilizadas e expandidas.
• Integração poderosa com IA: LangChain permite integrar facilmente modelos de IA avançados para tarefas complexas.
• Escalabilidade: Facilidade para expandir a aplicação conforme as necessidades aumentam.

📌 Conclusão

Este guia proporcionou uma visão abrangente de como implementar uma aplicação robusta usando MCP, FastMCP e LangChain. Com esta base, você poderá criar projetos inovadores, eficientes e escaláveis.

A arquitetura de sistema com FastAPI pode conduzir um padrão de arquitetura MVC (Model-View-Controller) ou similar, onde a lógica de negócios (Model) é separada da interface do usuário (View) e controlada por um controlador (Controller).

Models

Representa os dados e as regras de negócios relacionadas a eles

Responsável por lidar com a lógica de negócios do aplicativo e acessar os dados. Ela pode ser implementada usando uma biblioteca de ORM, como SQLAlchemy ou Tortoise ORM. Com o ORM, você pode definir os seus modelos de banco de dados como classes Python e, em seguida, interagir com o banco de dados usando essas classes.

# /models/car.py
from pydantic import BaseModel  
  
  
class Car(BaseModel):  
    id: str  
    name: str

Controller:

Lida com a lógica de controle e gerencia as interações entre o modelo e a visualização.

A camada do controlador é responsável por controlar o fluxo de dados entre o modelo e a visualização. Ela pode ser implementada como uma camada intermediária que recebe solicitações da visualização, chama a camada do modelo para obter dados e, em seguida, retorna uma resposta adequada à visualização.

# /controller/car_controller.py
from models.Car import Car  
  
  
class CarController:  
    @classmethod  
    async def get(cls) -> Car:  
        return Car(id="1", name="BMW")

Views

Responsável pela apresentação dos dados ao usuário.

É responsável por receber solicitações do cliente e retornar uma resposta adequada. Ela pode ser implementada usando rotas FastAPI que correspondem às URLs da API. A view pode chamar a camada do modelo para obter dados e, em seguida, usar um esquema FastAPI para serializar a resposta em um formato adequado, como JSON.

# /views/car_view.py
from fastapi import APIRouter  
  
from controllers.car_controller import CarController  
from models.Car import Car  
  

router_car = APIRouter()  
  

@router_car.get("/car", response_model=Car, summary="Get car")  
async def get_todos() -> Car:  
    return await CarController().get()

O arquivo main.py é o ponto de entrada para a aplicação FastAPI e configura o servidor e as rotas para todas as visualizações da API.

# main.py
from fastapi import FastAPI  
  
from views.car_view import router_car  
  
app = FastAPI()  
  
app.router.include_router(router_car, prefix="/api/v1", tags=["car"])  
  
if __name__ == "__main__":  
    import uvicorn  
  
    uvicorn.run(app, host="localhost", port=8000)

Em resumo, o padrão MVC é uma maneira eficaz de organizar o código em sua aplicação FastAPI, separando a lógica de negócios (Model), as rotas e funções de manipulação de solicitações HTTP (Controller) e a exibição dos dados (View).