README.md

Consumindo um servidor da extensão AI Toolkit para Visual Studio Code

Quando você está criando um agente de IA, não se trata apenas de gerar respostas inteligentes; é também sobre dar ao seu agente a capacidade de agir. É aí que entra o Model Context Protocol (MCP). O MCP facilita o acesso dos agentes a ferramentas e serviços externos de forma consistente. Pense nisso como conectar seu agente a uma caixa de ferramentas que ele realmente pode usar.

Suponha que você conecte um agente ao seu servidor MCP de calculadora. De repente, seu agente pode realizar operações matemáticas apenas recebendo um comando como “Quanto é 47 vezes 89?” — sem necessidade de lógica codificada manualmente ou APIs personalizadas.

Visão geral

Esta lição mostra como conectar um servidor MCP de calculadora a um agente com a extensão AI Toolkit no Visual Studio Code, permitindo que seu agente execute operações matemáticas como adição, subtração, multiplicação e divisão por meio de linguagem natural.

O AI Toolkit é uma extensão poderosa para Visual Studio Code que simplifica o desenvolvimento de agentes. Engenheiros de IA podem criar e testar modelos generativos de IA facilmente — localmente ou na nuvem. A extensão suporta a maioria dos principais modelos generativos disponíveis hoje.

Nota: O AI Toolkit atualmente suporta Python e TypeScript.

Objetivos de aprendizagem

Ao final desta lição, você será capaz de:

• Consumir um servidor MCP via AI Toolkit.
• Configurar a configuração de um agente para que ele descubra e utilize ferramentas fornecidas pelo servidor MCP.
• Utilizar ferramentas MCP por meio de linguagem natural.

Abordagem

Aqui está como devemos proceder em alto nível:

• Criar um agente e definir seu prompt do sistema.
• Criar um servidor MCP com ferramentas de calculadora.
• Conectar o Agent Builder ao servidor MCP.
• Testar a invocação das ferramentas do agente via linguagem natural.

Ótimo, agora que entendemos o fluxo, vamos configurar um agente de IA para aproveitar ferramentas externas via MCP, ampliando suas capacidades!

Pré-requisitos

• Visual Studio Code
• AI Toolkit para Visual Studio Code

Exercício: Consumindo um servidor

Neste exercício, você vai construir, executar e aprimorar um agente de IA com ferramentas de um servidor MCP dentro do Visual Studio Code usando o AI Toolkit.

-0- Passo inicial, adicione o modelo OpenAI GPT-4o aos Meus Modelos

O exercício utiliza o modelo GPT-4o. O modelo deve ser adicionado aos Meus Modelos antes de criar o agente.

1. Abra a extensão AI Toolkit na Activity Bar.
2. Na seção Catalog, selecione Models para abrir o Model Catalog. Selecionar Models abre o Model Catalog em uma nova aba do editor.
3. Na barra de busca do Model Catalog, digite OpenAI GPT-4o.
4. Clique em + Add para adicionar o modelo à sua lista de Meus Modelos. Certifique-se de ter selecionado o modelo Hosted by GitHub.
5. Na Activity Bar, confirme que o modelo OpenAI GPT-4o aparece na lista.

-1- Criar um agente

O Agent (Prompt) Builder permite criar e personalizar seus próprios agentes alimentados por IA. Nesta seção, você criará um novo agente e atribuirá um modelo para conduzir a conversa.

1. Abra a extensão AI Toolkit na Activity Bar.
2. Na seção Tools, selecione Agent (Prompt) Builder. Selecionar Agent (Prompt) Builder abre o construtor em uma nova aba do editor.
3. Clique no botão + New Agent. A extensão abrirá um assistente via Command Palette.
4. Digite o nome Calculator Agent e pressione Enter.
5. No Agent (Prompt) Builder, no campo Model, selecione o modelo OpenAI GPT-4o (via GitHub).

-2- Criar um prompt do sistema para o agente

Com o agente criado, é hora de definir sua personalidade e propósito. Nesta seção, você usará o recurso Generate system prompt para descrever o comportamento esperado do agente — neste caso, um agente calculadora — e deixar o modelo gerar o prompt do sistema para você.

1. Na seção Prompts, clique no botão Generate system prompt. Esse botão abre o construtor de prompt que usa IA para gerar um prompt do sistema para o agente.
2. Na janela Generate a prompt, insira o seguinte: You are a helpful and efficient math assistant. When given a problem involving basic arithmetic, you respond with the correct result.
3. Clique no botão Generate. Uma notificação aparecerá no canto inferior direito confirmando que o prompt do sistema está sendo gerado. Quando a geração for concluída, o prompt aparecerá no campo System prompt do Agent (Prompt) Builder.
4. Revise o System prompt e modifique se necessário.

-3- Criar um servidor MCP

Agora que você definiu o prompt do sistema do seu agente — guiando seu comportamento e respostas — é hora de equipar o agente com capacidades práticas. Nesta seção, você criará um servidor MCP de calculadora com ferramentas para executar cálculos de adição, subtração, multiplicação e divisão. Esse servidor permitirá que seu agente realize operações matemáticas em tempo real em resposta a comandos em linguagem natural.

O AI Toolkit vem com templates para facilitar a criação do seu próprio servidor MCP. Usaremos o template Python para criar o servidor MCP de calculadora.

Nota: O AI Toolkit atualmente suporta Python e TypeScript.

1. Na seção Tools do Agent (Prompt) Builder, clique no botão + MCP Server. A extensão abrirá um assistente via Command Palette.

2. Selecione + Add Server.

3. Selecione Create a New MCP Server.

4. Selecione python-weather como template.

5. Selecione Default folder para salvar o template do servidor MCP.

6. Insira o seguinte nome para o servidor: Calculator

7. Uma nova janela do Visual Studio Code será aberta. Selecione Yes, I trust the authors.

8. Usando o terminal (Terminal > New Terminal), crie um ambiente virtual: python -m venv .venv

9. No terminal, ative o ambiente virtual:

   1. Windows - .venv\Scripts\activate
   2. macOS/Linux - source venv/bin/activate

10. No terminal, instale as dependências: pip install -e .[dev]

11. Na visualização Explorer da Activity Bar, expanda o diretório src e selecione o arquivo server.py para abrir no editor.

12. Substitua o código no arquivo server.py pelo seguinte e salve:

    """
    Sample MCP Calculator Server implementation in Python.
    
    
    This module demonstrates how to create a simple MCP server with calculator tools
    that can perform basic arithmetic operations (add, subtract, multiply, divide).
    """
    
    from mcp.server.fastmcp import FastMCP
    
    server = FastMCP("calculator")
    
    @server.tool()
    def add(a: float, b: float) -> float:
        """Add two numbers together and return the result."""
        return a + b
    
    @server.tool()
    def subtract(a: float, b: float) -> float:
        """Subtract b from a and return the result."""
        return a - b
    
    @server.tool()
    def multiply(a: float, b: float) -> float:
        """Multiply two numbers together and return the result."""
        return a * b
    
    @server.tool()
    def divide(a: float, b: float) -> float:
        """
        Divide a by b and return the result.
        
        Raises:
            ValueError: If b is zero
        """
        if b == 0:
            raise ValueError("Cannot divide by zero")
        return a / b

-4- Execute o agente com o servidor MCP de calculadora

Agora que seu agente tem ferramentas, é hora de usá-las! Nesta seção, você enviará comandos para o agente testar e validar se ele utiliza a ferramenta adequada do servidor MCP de calculadora.

Você vai rodar o servidor MCP de calculadora na sua máquina local como cliente MCP via Agent Builder.

1. Pressione F5 to start debugging the MCP server. The Agent (Prompt) Builder will open in a new editor tab. The status of the server is visible in the terminal.
2. In the User prompt field of the Agent (Prompt) Builder, enter the following prompt: I bought 3 items priced at $25 each, and then used a $20 discount. How much did I pay?
3. Click the Run button to generate the agent's response.
4. Review the agent output. The model should conclude that you paid $55.
5. Here's a breakdown of what should occur:
   • The agent selects the multiply and substract tools to aid in the calculation.
   • The respective a and b values are assigned for the multiply tool.
   • The respective a and b valores são atribuídos para a ferramenta subtract.
   • A resposta de cada ferramenta é mostrada na respectiva Tool Response.
   • O resultado final do modelo aparece na Model Response final.
6. Envie comandos adicionais para testar mais o agente. Você pode modificar o prompt existente no campo User prompt clicando nele e substituindo o texto.
7. Quando terminar de testar, você pode parar o servidor pelo terminal pressionando CTRL/CMD+C para encerrar.

Tarefa

Tente adicionar uma nova entrada de ferramenta no seu arquivo server.py (ex: retornar a raiz quadrada de um número). Envie comandos adicionais que exijam que o agente utilize sua nova ferramenta (ou as ferramentas existentes). Não esqueça de reiniciar o servidor para carregar as ferramentas adicionadas.

Solução

Solution

Principais aprendizados

Os principais aprendizados deste capítulo são:

• A extensão AI Toolkit é um ótimo cliente que permite consumir servidores MCP e suas ferramentas.
• Você pode adicionar novas ferramentas a servidores MCP, ampliando as capacidades do agente para atender a requisitos em evolução.
• O AI Toolkit inclui templates (ex: templates Python para servidores MCP) que simplificam a criação de ferramentas personalizadas.

Recursos adicionais

• Documentação do AI Toolkit

Próximos passos

• Próximo: Testes & Depuração

Aviso Legal:
Este documento foi traduzido utilizando o serviço de tradução automática Co-op Translator. Embora nos esforcemos para garantir a precisão, esteja ciente de que traduções automáticas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autorizada. Para informações críticas, recomenda-se tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução.