Observação:

Crie um Agente de IA com Servidor de Protocolo de Comunicação Multiagente para Resolução de Faturas

Introdução

As empresas que lidam com um grande volume de produtos - como distribuidores, indústrias e cadeias de varejo - muitas vezes enfrentam o desafio de identificar produtos com base em descrições textuais imprecisas, incompletas ou variadas. Em ambientes onde os dados são inseridos manualmente, erros de digitação, abreviações e diferentes nomes comerciais podem dificultar a identificação correta de itens em sistemas como Enterprise Resource Planning (ERP), Customer Relationship Management (CRM) e plataformas de e-commerce.

Nesse cenário, há uma necessidade comum de ferramentas que possam:

Neste tutorial, aprenderemos a criar um agente de IA especializado na resolução de inconsistências em documentos fiscais de devolução ao cliente. O agente é capaz de interagir com um servidor MCP que fornece ferramentas de pesquisa vetorial e recuperação de faturas, permitindo que o agente localize automaticamente a fatura de C/R original da empresa com base nas informações fornecidas pelo cliente.

Um Servidor MCP (Model Context Protocol) é um componente de software responsável por mediar a comunicação entre agentes inteligentes e serviços externos por meio de um protocolo padronizado de mensagens e ferramentas. Ele atua como uma ponte entre os modelos de linguagem (LLMs) e as APIs existentes, permitindo que os agentes de IA acessem funcionalidades específicas de sistemas legados sem a necessidade de reescrevê-los ou adaptá-los diretamente.

Como isso funciona?

O servidor MCP:

Uso com Aplicativos Legados

Muitas vezes, os aplicativos legados já fornecem funcionalidade por meio de bancos de dados, arquivos ou APIs internas. Com um Servidor MCP, você pode:

Vantagens

Esse agente é baseado em um modelo de linguagem da Oracle Cloud Infrastructure (OCI) Generative AI e se integra a ferramentas declaradas dinamicamente gerenciadas por um servidor MCP.

Com a integração desses dois componentes, o sistema permite que um agente baseado no Oracle LLM:

Este design modular permite a reutilização e a fácil evolução do sistema para domínios diferentes das faturas.

Objetivos

Pré-requisitos

Instale o requirements.txt com:

pip install -r requirements.txt

Tarefa 1: Criar um Oracle Database 23ai (Sempre Gratuito)

Nesta tarefa, aprenderemos a provisionar um Oracle Database 23ai no modo Always Free. Esta versão oferece um ambiente totalmente gerenciado, ideal para desenvolvimento, teste e aprendizado, sem custo adicional.

  1. Faça log-in na Console do OCI, navegue até Oracle Database, Autonomous Database e clique em Criar Instância do Autonomous Database.

  2. Digite as seguintes informações.

    • Nome do Banco de Dados: Informe um nome de identificação para sua instância.
    • Tipo de Carga de Trabalho: Selecione Data Warehouse ou Processamento de Transações, de acordo com suas necessidades.
    • Compartimento: Selecione um compartimento apropriado para organizar seus recursos.

  3. Selecione Always Free para garantir que a instância seja provisionada gratuitamente.

  4. Crie uma senha segura para o usuário ADMIN, que será usada para acessar o banco de dados.

  5. Verifique as definições e clique em Criar Autonomous Database. Aguarde alguns minutos para que a instância seja provisionada e esteja disponível para uso.

Tarefa 2: Executar o Script de Criação de Tabela do Autonomous Database

Prepare o banco de dados para nosso caso de uso. Faça download do script SQL e execute-o aqui: script.sql que cria três tabelas essenciais (PRODUCTS, INVOICE e ITEM_INVOICE) para o cenário de reconciliação de NFFs com agentes de IA.

  1. Vá para a Console do OCI, navegue até Oracle Database, Autonomous Database e clique no nome da instância recém-criada.

  2. Clique em Database Actions e em SQL para abrir a console SQL no browser.

  3. Faça download e abra o arquivo script.sql localmente e cole todo o conteúdo no editor da console SQL.

  4. Clique em Executar ou pressione Ctrl + Enter. Aguarde a confirmação de que os comandos foram executados com sucesso.

  5. Execute os comandos a seguir para verificar se as tabelas foram criadas.

    SELECT table_name FROM user_tables;

Tarefa 3: Inserir Dados de Exemplo em Tabelas

Insira dados fictícios que simularão um cenário real para a aplicação de agentes de IA. Usaremos dois scripts SQL:

Esses dados serão usados pelos agentes de IA para resolver inconsistências nas faturas de devoluções.

  1. Vá para a Console do OCI, navegue até Oracle Database, Autonomous Database e clique no nome da instância recém-criada.

  2. Clique em Database Actions e em SQL para abrir a console SQL no browser.

  3. Faça download do conteúdo do arquivo insert_products_books.sql e cole-o no editor de SQL.

  4. Clique em Executar ou pressione Ctrl + Enter.

  5. Agora, faça download e abra o conteúdo do arquivo invoice_data_insert.sql e cole-o no editor.

  6. Clique em Executar ou pressione Ctrl + Enter.

  7. Execute o seguinte comando para verificar os dados.

    SELECT * FROM PRODUCTS;
SELECT * FROM INVOICE;
SELECT * FROM ITEM_INVOICE;

Tarefa 4: Criar e Compilar a Função de Pesquisa Avançada no Banco de Dados

Crie uma função PL/SQL chamada fn_advanced_search, que executa pesquisas inteligentes por palavras-chave em descrições de produtos. Essa função será usada por agentes de IA como parte da ferramenta resolve_ean, permitindo que eles encontrem o código EAN mais próximo com base na descrição fornecida por um cliente na nota de devolução.

O que a função faz?

Siga as etapas:

  1. Copie e cole o script similarity_search.sql completo na console SQL do banco de dados autônomo.

    Isso inclui:

    • Criando a tabela products (se ainda não tiver sido feita).
    • Criando um índice de texto.
    • Tipos product_result e product_result_tab.
    • A função fn_advanced_search.
    • Testes opcionais.

  2. Execute o script completo. O resultado deve ser Function created e Type created.

  3. Execute a consulta a seguir para testar a função com descrições simuladas.

    SELECT *
FROM TABLE(fn_advanced_search('harry poter askaban'))
ORDER BY similarity DESC;

Tarefa 5: Vectorizar Produtos para Pesquisa Semântica com IA

Nesta tarefa, vamos complementar a pesquisa avançada baseada em SQL com uma nova abordagem baseada em vetores semânticos. Isso será especialmente útil para agentes de IA que usam incorporações (representações numéricas de frases) para comparar a similaridade entre descrições de produtos - de forma mais flexível e inteligente do que pesquisas de palavras ou fonéticas.

Para isso, usaremos o script Python (process_vector_products.py), que se conecta ao banco de dados Oracle, extrai os produtos da tabela PRODUCTS, transforma suas descrições em vetores (embeddings) e cria um índice vetorial usando o próprio banco de dados Oracle.

O que o script faz?

Observação: as incorporações são convertidas em bytes com np.float32.tobytes() para serem armazenadas como BLOB. Para recuperar os vetores, use np.frombuffer(blob, dtype=np.float32).

Esse formato permite que futuras pesquisas de similaridade sejam feitas diretamente usando SQL ou carregando os vetores do banco de dados para operações com np.dot, cosine_similarity ou integração com LLMs.

Esse script gera incorporações semânticas para produtos e grava esses vetores no banco de dados Oracle 23ai. Os principais pontos são destacados abaixo:

Execute o Script:

Lembre-se de que você precisa fazer download e configurar o Oracle Wallet. Execute-o no terminal.

python process_vector_products.py

Concluído! Os produtos no banco de dados foram vetorizados.

Por que isso é importante?

A busca vetorial é altamente eficaz para encontrar produtos mesmo quando a descrição é subjetiva, imprecisa ou em linguagem natural.

Compreender o Código: Agente LLM com Servidor MCP

Este projeto é composto por 3 componentes principais:

Entenda a funcionalidade de cada componente e realce com detalhes as partes mais importantes do código.

Tarefa 6: Configurar o Modelo e as Incorporações no Agente MCP

Vamos configurar o modelo de linguagem e as incorporações usadas pelo agente de conversação com base no protocolo MCP, usando os serviços OCI Generative AI.

  1. Configurar o Modelo de Idioma (LLM).

    O modelo de linguagem é responsável por interpretar mensagens, gerar respostas e atuar como o principal cérebro do agente.

    • Configure no arquivo main.py.

      from langchain_community.chat_models.oci_generative_ai import ChatOCIGenAI

llm = ChatOCIGenAI(
    model_id="cohere.command-r-08-2024",
    service_endpoint="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com",
    compartment_id="ocid1.compartment.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    auth_profile="DEFAULT",
    model_kwargs={"temperature": 0.1, "top_p": 0.75, "max_tokens": 2000}
)
      Parâmetro Descrição
      model_id ID do modelo de IA generativa, por exemplo, cohere.command-r-08-2024
      service_endpoint Ponto final regional do serviço Generative AI
      compartment_id OCID do compartimento do OCI
      auth_profile Nome do perfil configurado no arquivo ~/.oci/config
      model_kwargs Temperatura, top-p e tamanho da resposta

    • Liste os modelos disponíveis.

      • Usando a CLI do OCI:

        oci generative-ai model list --compartment-id <seu_compartment_id>

      • Usando o Python SDK:

        from oci.generative_ai import GenerativeAiClient
from oci.config import from_file

config = from_file(profile_name="DEFAULT")
client = GenerativeAiClient(config)

models = client.list_models(compartment_id=config["compartment_id"])
for model in models.data:
    print(model.display_name, model.model_id)

  2. Configure incorporações para pesquisa semântica.

    A busca por produtos semelhantes ou informações contextuais depende de incorporações vetoriais.

    Exemplo de uso no agente:

    @mcp.tool()
def search_vectorized_product(description: str) -> dict:
    """
        Searches for a product by description using embeddings.
    """
    return sercher.search_similar_products(description)

    Altere os parâmetros (product_search.py), conforme mostrado abaixo:

    
class SimilarProductSearch:
    def __init__(
            self,
            top_k=5,
            minimum_distance=1.0,
            model_id="cohere.embed-english-light-v3.0",
            service_endpoint="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com",
            compartment_id="ocid1.compartment.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
            auth_profile="DEFAULT",
            wallet_path="/WALLET_PATH/Wallet_oradb23ai",
            db_alias="oradb23ai_high",
            username="USER",
            password="Password"
    ):
    Parâmetro Descrição
    top_k Número de sugestões retornadas.
    minimum_distance Distância máxima para considerar o resultado relevante.
    model_id ID do modelo de incorporação no OCI (por exemplo, cohere.embed-english-light-v3.0).
    service_endpoint Ponto final regional do OCI Generative AI.
    compartment_id OCID do compartimento.
    auth_profile Nome do perfil no arquivo ~/.oci/config.
    wallet_path Caminho para a wallet do Oracle Database 23ai.
    db_alias Apelido do Banco de Dados.
    username Usuário do banco de dados.
    password Senha do banco de dados.

    Configure o servidor MCP:

    Assim como você fez ao executar o código process_vector_products.py, será necessário configurar o Oracle Wallet para o banco de dados Oracle Database 23ai.

    Modifique os parâmetros de acordo com suas configurações:

    import os

# Oracle Wallet settings
WALLET_PATH = "/path/to/Wallet"
DB_ALIAS = "oradb23ai_high"
USERNAME = "admin"
PASSWORD = "..."

# Define the environment variable required for the Oracle client
os.environ["TNS_ADMIN"] = WALLET_PATH

    Em seguida, execute o process_vector_products.py para vetorizar os produtos no Oracle Database 23ai.

    python process_vector_products.py

Com isso, o modelo LLM e as incorporações estão prontos para serem usados pelo agente MCP com LangGraph e LangChain.

  1. Execute o arquivo main.py usando o comando a seguir.

    python main.py

  2. Quando o prompt Você: for exibido, informe a seguinte instrução.

    { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26, "location": "SP"}

    Observação: O nome do livro Harry Potter e Azkaban está escrito errado, mas o mecanismo pode encontrá-lo sem problemas.

    img.png

    img_1.png

    Observe que os serviços foram executados:

    fetch_vectorized_product
resolve_ean
search_invoices_by_criteria

  3. Agora, insira a seguinte instrução.

    { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26}

    Você verá que não foi encontrado nenhum registro de documento fiscal. Isso ocorre porque o local é a chave para localizar uma NFF.

    img_2.png

  4. Agora, insira a seguinte instrução.

    { "customer": "Customer 108",  "description": "Harry Poter", "location": "SP"}

    Desta vez, inserimos o local, mas omitimos o preço unitário.

    img_3.png

    E ainda assim a fatura foi encontrada. Isto porque o preço não é fundamental, mas ajuda a fechar a lacuna para ser mais assertivo.

    Alguns exemplos de teste são:

     { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26, "location": "SP"}

 { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26}

 { "customer": "Customer 108",  "description": "Harry Poter askaban", "location": "SP"}

 { "customer": "Customer 108",  "description": "Harry Poter askaban", "price": 82.26, "location": "RJ"}

 { "customer": "Customer 125",  "description": "Harry Potter Chamber", "price": 79.16, "location": "SP"}

 { "customer": "Customer 125",  "description": "Harry Potter Chamber", "price": 79.15, "location": "SP"}

Tarefa 8: Exibir a Observabilidade com o Phoenix

Digite http://localhost:6006/ no seu navegador para ver a observabilidade com Phoenix.

img.png

img.png

img.png

Confirmações

Mais Recursos de Aprendizado

Explore outros laboratórios em docs.oracle.com/learn ou acesse mais conteúdo de aprendizado gratuito no canal do Oracle Learning YouTube. Além disso, acesse education.oracle.com/learning-explorer para se tornar um Oracle Learning Explorer.

Para obter a documentação do produto, visite o Oracle Help Center.