Integrando MCP (Model Context Protocol)

Nos capítulos anteriores, seu agente aprendeu a seguir instruções, se fundamentar em seus próprios dados usando File Search (RAG) e chamar ferramentas personalizadas.

Neste capítulo final, vamos conectar seu agente a um servidor MCP ao vivo — dando a ele acesso a capacidades externas como menus ao vivo, coberturas e gerenciamento de pedidos através de um protocolo padrão e seguro.

O Que É MCP e Por Que Usá-lo?

MCP (Model Context Protocol) é um padrão aberto para conectar agentes de IA a ferramentas externas, fontes de dados e serviços através de servidores MCP interoperáveis.
Em vez de integrar com APIs individuais, você conecta uma vez a um servidor MCP e automaticamente ganha acesso a todas as ferramentas que esse servidor expõe.

Benefícios do MCP

• 🧩 Interoperabilidade: uma forma universal de expor ferramentas de qualquer serviço para qualquer agente compatível com MCP.
• 🔐 Segurança e governança: gerencie centralmente acesso e permissões de ferramentas.
• ⚙️ Escalabilidade: adicione ou atualize ferramentas do servidor sem mudar o código do seu agente.
• 🧠 Simplicidade: mantenha integrações e lógica de negócio no servidor; mantenha seu agente focado em raciocínio.

Atualizar Seus Imports

Atualize seus imports no agent.py para incluir MCPTool:

import json
import os
import glob
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, FileSearchTool, FunctionTool, MCPTool, Tool
from openai.types.responses.response_input_param import FunctionCallOutput, ResponseInputParam

O Servidor MCP da Contoso Pizza

Para a Contoso Pizza, o servidor MCP expõe APIs para:

• 🧀 Pizzas: itens de menu disponíveis e preços
• 🍅 Coberturas: categorias, disponibilidade e detalhes
• 📦 Pedidos: criar, visualizar e cancelar pedidos de clientes

Você conectará seu agente a este servidor e dará acesso para usar as ferramentas dessas operações.

Adicionar a Ferramenta MCP

Adicione este código após sua seção de Ferramenta de Chamada de Função e antes de criar o toolset:

## -- MCP -- ##
mcpTool = MCPTool(
    server_label="contoso-pizza-mcp",
    server_url="<!--@include: ./variables/mcp-url.md-->",
    require_approval="never"
)
## -- MCP -- ##

Parâmetros Explicados

Parâmetro	Descrição
server_label	Um nome legível para logs e depuração.
server_url	O endpoint do servidor MCP.
require_approval	Define se chamadas requerem aprovação manual ("never" desabilita prompts).

TIP

💡 Em produção, use modos de aprovação mais restritivos para operações sensíveis.

Atualizar o Toolset

Adicione a ferramenta MCP ao seu toolset:

## Definir o toolset para o agente
toolset: list[Tool] = []
toolset.append(FileSearchTool(vector_store_ids=[vector_store.id]))
toolset.append(func_tool)
toolset.append(mcpTool)

Adicionar um ID de Usuário

Para fazer pedidos, o agente deve identificar o cliente.

1. Obtenha seu ID de Usuário
   Visite esta URL para registrar um cliente:
   

2. Atualize seu instrucoes.txt com seus detalhes de usuário ou passe o GUID no chat.

## Detalhes do usuário:
Nome: <SEU NOME>
UserId: <SEU GUID DE USUÁRIO>

3. (Opcional) Visualize seu painel de pedidos:
   

Experimentando

Agora é hora de testar seu agente conectado!
Execute o agente e experimente estes prompts:

Mostre-me as pizzas disponíveis.

Qual é o preço de uma pizza havaiana?

Quero pedir uma pizza margherita.

Resumo

Neste capítulo, você:

• Aprendeu o que é MCP (Model Context Protocol) e por que é útil
• Adicionou uma MCPTool ao seu toolset
• Conectou seu agente a um servidor MCP externo
• Testou o agente de ponta a ponta com menus ao vivo e pedidos

Amostra de código final

import json
import os
import glob
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, FileSearchTool, FunctionTool, MCPTool, Tool
from openai.types.responses.response_input_param import FunctionCallOutput, ResponseInputParam

load_dotenv()

vector_store_id = ""  # Defina o ID do seu vector store se já tiver um

## Configurar Cliente do Projeto
project_client = AIProjectClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
openai_client = project_client.get_openai_client()


## -- BUSCA DE ARQUIVOS -- ##

if vector_store_id:
    vector_store = openai_client.vector_stores.retrieve(vector_store_id)
    print(f"Usando vector store existente (id: {vector_store.id})")
else:
    # Criar vector store para busca de arquivos
    vector_store = openai_client.vector_stores.create(name="ContosoPizzaStores")
    print(f"Vector store criado (id: {vector_store.id})")

    # Fazer upload de arquivo para o vector store
    for file_path in glob.glob("documents/*.md"):
        file = openai_client.vector_stores.files.upload_and_poll(
            vector_store_id=vector_store.id, file=open(file_path, "rb")
        )
        print(f"Arquivo enviado para o vector store (id: {file.id})")
## -- BUSCA DE ARQUIVOS -- ##


## -- Ferramenta de Chamada de Função -- ##
func_tool = FunctionTool(
    name="get_pizza_quantity",
    parameters={
        "type": "object",
        "properties": {
            "people": {
                "type": "integer",
                "description": "O número de pessoas para pedir pizza",
            },
        },
        "required": ["people"],
        "additionalProperties": False,
    },
    description="Obtém a quantidade de pizza a pedir baseado no número de pessoas.",
    strict=True,
)

def get_pizza_quantity(people: int) -> str:
    """Calcula o número de pizzas a pedir baseado no número de pessoas.
        Assume que cada pizza alimenta 2 pessoas.
    Args:
        people (int): O número de pessoas para pedir pizza.
    Returns:
        str: Uma mensagem indicando o número de pizzas a pedir.
    """
    print(f"[CHAMADA DE FUNÇÃO:get_pizza_quantity] Calculando quantidade de pizza para {people} pessoas.")
    return f"Para {people} você precisa pedir {people // 2 + people % 2} pizzas."
## -- Ferramenta de Chamada de Função -- ##


## -- MCP -- ##
mcpTool = MCPTool(
    server_label="contoso-pizza-mcp",
    server_url="https://pizza-mcp-server.prouddune-f79ccb2b.westeurope.azurecontainerapps.io/mcp",
    require_approval="never"
)
## -- MCP -- ##


## Definir o toolset para o agente
toolset: list[Tool] = []
toolset.append(FileSearchTool(vector_store_ids=[vector_store.id]))
toolset.append(func_tool)
toolset.append(mcpTool)


## Criar um Foundry Agent
agent = project_client.agents.create_version(
    agent_name="hello-world-agent",
    definition=PromptAgentDefinition(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        instructions=open("instrucoes.txt").read(),
        tools=toolset,
    ),
)
print(f"Agente criado (id: {agent.id}, nome: {agent.name}, versão: {agent.version})")


## Criar uma conversa para a interação do agente
conversation = openai_client.conversations.create()
print(f"Conversa criada (id: {conversation.id})")

## Conversar com o agente

while True:
    # Obter a entrada do usuário
    user_input = input("Você: ")

    if user_input.lower() in ["exit", "quit", "sair"]:
        print("Saindo do chat.")
        break

    # Obter a resposta do agente
    response = openai_client.responses.create(
        conversation=conversation.id,
        input=user_input,
        extra_body={"agent": {"name": agent.name, "type": "agent_reference"}},
    )

    # Tratar chamadas de função na resposta
    input_list: ResponseInputParam = []
    for item in response.output:
        if item.type == "function_call":
            if item.name == "get_pizza_quantity":
                # Executar a lógica da função para get_pizza_quantity
                pizza_quantity = get_pizza_quantity(**json.loads(item.arguments))
                # Fornecer resultados da chamada de função ao modelo
                input_list.append(
                    FunctionCallOutput(
                        type="function_call_output",
                        call_id=item.call_id,
                        output=json.dumps({"pizza_quantity": pizza_quantity}),
                    )
                )

    if input_list:
        response = openai_client.responses.create(
            previous_response_id=response.id,
            input=input_list,
            extra_body={"agent": {"name": agent.name, "type": "agent_reference"}},
        )    

    # Imprimir a resposta do agente
    print(f"Assistente: {response.output_text}")

Traduzido usando GitHub Copilot.