MCP + OpenAI Agents SDK: Como construir um poderoso agente de IA

Quando abriu as suasAgents SDKAlgumas semanas atrás, os desenvolvedores em todo o mundo foram surpreendidos – e por uma boa razão! Finalmente, uma maneira simples de construir agentes de IA orientados a objetivos que realmente possam raciocinar eFaça o trabalho feito

Quase na mesma respiração,MCPexplodiu na cena, rapidamente se tornando a próxima tendência quente nesta paisagem de IA selvagem.Então, por que não quebrar essas duas potências juntas?!

Nesse guia,we're going to forge a formidable AI agentaproveitando o OpenAI Agents SDK e conectando-o diretamente às ferramentas do mundo real fornecidas por um servidor MCP. Prepare-se para sobrecarregar sua IA!

Introdução rápida à integração do MCP + OpenAI Agents SDK

O OpenAI Agents SDK é um dos kit de ferramentas Python mais populares para a criação de agentes inteligentes de IA, permitindo-lhes raciocinar e agir.Mas aqui está o kicker: sem informações externas, eles muitas vezes ficam presos em uma bolha de dados de treinamento.

Pense em MCP como a porta USB-C universal para sua IA, dando-lhe uma maneira padronizada de se conectar.qualquerfonte de dados externa ou ferramenta – arquivos locais, APIs, bancos de dados, você nomeia-os.

Integrar o MCP com o OpenAI Agents SDK significa que seus agentes obtêm contexto dinâmico em tempo real, transformando-os de bots inteligentes, mas isolados, em exploradores de dados e tomadores de ação!

Construir um agente de IA com integração MCP usando o OpenAI Agents SDK

Bom, teoria suficiente. você consegue – o MCP sobrecarrega os agentes de IA como se fossemHomem de Ferroem seu icônico traje de metal.

Nesta seção passo a passo, vamos usar o OpenAI Agents SDK – o novo Python SDK da OpenAI – para construir um agente de IA com integração MCP.native MCP support, o que significa que seu agente pode ir de inteligente paraSuperpotênciaem segundos.

Agora, pequena captura: a API da OpenAI não é gratuita. 😅 Assim, neste guia,we’ll run it using Gemini as the LLM engine instead(Não se preocupe - mostraremos como trocar em OpenAI ou qualquer outro modelo também ).

Mas espere – que servidor MCP estamos usando?

Grande pergunta! Para começar rapidamente, estamos conectandoServiço de Dados MCP- um servidor MCP construído para tarefas de automação da web e dados. Permite que seu agente de IA procure, navegue, tome ações e extraia dados em tempo real da Web - com a stealth incorporada para contornar CAPTCHAs eArmadilhas anti-bot.

Especificamente, abaixo estão todas as ferramentas suportadas pelo servidor MCP Bright Data ️:

search_engine

Scrape dados SERP (do Google, Bing, Yandex e mais)

scrape_as_markdown

Raspar um URL e devolver conteúdo em Markdown limpo

scrape_as_html

Escreva um URL e retorne o conteúdo HTML completo

session_stats

Ver o uso da ferramenta durante a sessão atual

web_data_amazon_product

Obter informações de produtos da Amazon por URL

web_data_amazon_product_reviews

Avaliações da Amazon para um produto

web_data_linkedin_person_profile

Dados do perfil do LinkedIn

web_data_linkedin_company_profile

Fechar dados da empresa LinkedIn

web_data_zoominfo_company_profile

Obter o perfil da empresa ZoomInfo

web_data_instagram_profiles

Detalhes do perfil do Instagram

web_data_instagram_posts

Obtenha dados do Instagram

web_data_instagram_reels

Gravar dados reais do Instagram

web_data_instagram_comments

Fetch comentários de uma postagem no Instagram

web_data_facebook_posts

Extrair informações do post do Facebook

web_data_facebook_marketplace_listings

Obtenha listas do Facebook Marketplace

web_data_facebook_company_reviews

Scrape comentários de negócios do Facebook

web_data_x_posts

Retirar dados de X (anteriormente Twitter) posts

web_data_zillow_properties_listing

Obter listas de propriedades Zillow

web_data_booking_hotel_listings

FetchO Booking.comLista de hotéis

web_data_youtube_videos

Extrair metadados de vídeos do YouTube

scraping_browser_navigate

Navegue para um novo URL em um navegador virtual

scraping_browser_go_back

Voltar a uma página no navegador

scraping_browser_go_forward

Avançar uma página no navegador

scraping_browser_click

Clique em um elemento de página (needs selector)

scraping_browser_links

Obter todos os links e seletores na página

scraping_browser_type

Tipar em um formulário ou entrada

scraping_browser_wait_for

Espere que um elemento apareça

scraping_browser_screenshot

Capturar uma captura de tela da página atual

scraping_browser_get_html

Obtenha HTML bruto da página

scraping_browser_get_text

Extrair conteúdo de texto da página

Pronto para rolar? veja como obter seu agente de IA falando com o servidor MCP para poder ilimitado!

Passo #1: Configuração do projeto

Para seguir junto com esta seção de tutorial, certifique-se de que você tem os seguintes pré-requisitos no lugar:

• Python 3.10+ instalado localmente
• Node.js instalado localmente
• Uma chave API de um provedor de LLM suportado para o OpenAI Agents SDK (recomendamos Gemini para este)

Vamos pular o aborrecido fluxo de configuração e assumir que você já criou um projeto Python com esta estrutura:

/openai-agents-mcp
├── venv/
├── .env
└── agent.py

Agora, ative o seu ambiente virtual (venv/Instale os pacotes necessários:

pip install openai-agents python-dotenv

Onde é:

• openai-agents é o OpenAI Agents Python SDK – sua porta de entrada para a magia do agente de IA
• python-dotenv é para ler valores de um arquivo .env

Em seguida, abreagent.pyÉ hora de ler essas variáveis ambientais e se preparar para o lançamento do agente:

import asyncio
from dotenv import load_dotenv
import os
from agents import (
    Runner,
    Agent,
    OpenAIChatCompletionsModel,
    set_default_openai_client,
    set_tracing_disabled
)
from openai import AsyncOpenAI
from agents.mcp import MCPServerStdio

# Load environment variables from the .env file
load_dotenv()

async def run():
    # AI Agent logic goes here...
    pass

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

Boom!Você está de pé e correndo com os fundamentos.

Passo #2: Comece com o Bright Data MCP Server

Então, vocêQuer que seu agente de IA fale com um servidor MCP?

Bem, adivinhe o que – você precisará de um servidor MCP em execução primeiro (sim,Capitão óbvioAvaliação do dever!

Como mencionado anteriormente, usaremos oBright Data MCP ServerPor isso, em primeiro lugar,Pegue sua chave da API e inicialize o servidor de acordo com os documentos oficiais do servidor MCP Bright Data.

Quando estiver pronto, inicie o servidor com este comando:

npx -y @brightdata/mcp 

Se tudo estiver configurado corretamente, você deve ver uma saída semelhante a esta:

Checking for required zones...
Required zone "mcp_unlocker" already exists
Starting server...

Muito bom!

Agora, configure as variáveis de ambiente que o agente usará para se conectar ao servidor MCP Bright Data..envFaça um arquivo e adicione essas duas linhas:

BRIGHT_DATA_API_TOKEN="<YOUR_BRIGHT_DATA_API_TOKEN>"
BRIGHT_DATA_BROWSER_AUTH="<BRIGHT_DATA_BROWSER_AUTH>"

Substitua os detentores de lugar pelos valores obtidos, conforme explicado nos documentos do servidor MCP Bright Data.

Voltar emagent.pyLeia em dois versos como este:

BRIGHT_DATA_API_TOKEN = os.getenv("BRIGHT_DATA_API_TOKEN")
BRIGHT_DATA_BROWSER_AUTH = os.getenv("BRIGHT_DATA_BROWSER_AUTH")

Usaremos estes valores em breve ao inicializar a conexão MCP a partir do código.

E assim como isso - bam 💥 - seu servidor MCP está em andamento, em execução e pronto para servir seu agente de IA como um lado leal.

Passo #3: Crie seu agente de IA

Como teimado na introdução desta seção, vamos usar Gemini (yep, o LLM brilhante do Google) com o OpenAI Agents SDK.

Primeiro de tudo -Você pode até fazer isso?Em segundo lugar –Por que não usar o OpenAI diretamente?

ResponseSim, você pode fazer isso! 🙂Gemini exposes an OpenAI-compatible API, o que significa que você pode conectá-lo diretamente ao OpenAI Agents SDK como uma substituição drop-in.It’s free— Ao contrário de OpenAI, que gosta de cobrar pelo token.

Então, aqui está por que faz sentido usar Gemini em vez de OpenAI diretamente! 💡

Basta chit-chat, vamos arrastar as coisas ☀. Primeiro, pegue o seuGemini API Key do Google AI Studioe pule-o em seu.envArquivo em:

GEMINI_API_KEY="<YOUR_GEMINI_API_KEY>"

Em seguida, emagent.pyLeia a chave assim:

GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")

Agora, construa uma função que liga tudo juntos – oGemini model, OpenAI SDK, and the MCP server(que vamos configurar no código em breve ️):

async def create_mcp_ai_agent(mcp_server):
    # Initialize Gemini client using its OpenAI-compatible interface
    gemini_client = AsyncOpenAI(
        api_key=GEMINI_API_KEY,
        base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
    )

    # Set the default OpenAI client to Gemini
    set_default_openai_client(gemini_client)
    # Disable tracing to avoid tracing errors being logged in the terminal
    set_tracing_disabled(True)

    # Create an agent configured to use the MCP server and Gemini model
    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant",
        model=OpenAIChatCompletionsModel(
            model="gemini-2.0-flash",
            openai_client=gemini_client,
        ),
        mcp_servers=[mcp_server]
    )

    return agent

Se você quiser usar um modelo suportado diferente (como Claude, Mistral ou outros modelos), basta trocar obase_urlnome do modelo em conformidade.

Extra: Quer usar o OpenAI em vez disso?Não há problema.OPENAI_API_KEYSubstitua a lógica acima por:

async def create_mcp_ai_agent(mcp_server):
    # Create an agent configured to use the MCP server and Gemini model
    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant",
        mcp_servers=[mcp_server]
    )

    return agent

Intercâmbio fácil, a mesma interface – essa é a beleza do SDK... 😎

Se você está se perguntando onde omcp_serverO argumento vem de – vamos inicializá-lo no próximo passo ( alerta de spoiler).

Passo #4: Iniciar o servidor MCP

Dentro do seurun()função async, spin up o servidor MCP Bright Data usandonpxcomo este:

async with MCPServerStdio(
    name="Bright Data web data MCP server, via npx",
    params={
        "command": "npx",
        "args": ["-y", "@brightdata/mcp"],
        "env": {
            "API_TOKEN": BRIGHT_DATA_API_TOKEN,
            "BROWSER_AUTH": BRIGHT_DATA_BROWSER_AUTH,
        }
    },
    client_session_timeout_seconds=180   # To avoid timeout errors
) as server:
    # Create and initialize the AI agent with the running MCP server
    agent = await create_mcp_ai_agent(server)

    # AI agent loop logic...

️ O que está acontecendo aqui? Isto inicia o servidor MCP usandonpx -y @brightdata/mcp, passando em suas credenciais através de variáveis ambientais.

Nota: Não se esqueça de baterclient_session_timeout_secondsDois180segundos (o padrão é52) PorqueRastreamento em tempo real, resolução de CAPTCHA e movimentos de ninja anti-botexecutado pelo servidor MCP Bright Data leva tempo . Você não quer que ele tenha um tempo no meio da missão.

A única coisa que resta é desligar o loop do agente de IA... Vamos envolver.

Passo #5: Defina o Loop de Agente AI

Dentro do bloco de assíncope do servidor MCP, lance um loop REPL (Leia-Eval-Imprimir) para que os usuários possam digitar seus pedidos, enviá-los através do agente alimentado pelo MCP e recuperar a magia ✨:

while True:
    # Read the user's request
    request = input("Your request -> ")

    # Exit condition
    if request.lower() == "exit":
        print("Exiting the agent...")
        break

    # Run the request through the agent
    output = await Runner.run(agent, input=request)

    # Print the result to the user
    print(f"Output -> \n{output.final_output}\n\n")

Este pequeno fragmento de Python é o centro de comando do seu agente de IA. Ele continuamente captura suas solicitações, as alimenta ao agente e, em seguida, espalha o resultado final e glorioso.

Você só teve esse momento “whoa”?Se não, deixe-me esclarecer isso para você:you just wired up a full AI agent loop using the OpenAI Agents SDK + Bright Data’s MCP server + Gemini!

Agora você está pronto para olhar para o código completo, tudo apertado como um belo monstro de automação de IA de Frankenstein.

Passo #6: Coloque tudo em conjunto

Este é o seu script de Python final para a integração OpenAI Agents SDK + MCP (powered by Gemini to save money ):

import asyncio
from dotenv import load_dotenv
import os
from agents import (
    Runner,
    Agent,
    OpenAIChatCompletionsModel,
    set_default_openai_client,
    set_tracing_disabled
)
from openai import AsyncOpenAI
from agents.mcp import MCPServerStdio

# Load environment variables from the .env file
load_dotenv()

# Read the required secrets envs from environment variables
BRIGHT_DATA_API_TOKEN = os.getenv("BRIGHT_DATA_API_TOKEN")
BRIGHT_DATA_BROWSER_AUTH = os.getenv("BRIGHT_DATA_BROWSER_AUTH")
GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")

async def create_mcp_ai_agent(mcp_server):
    # Initialize Gemini client using its OpenAI-compatible interface
    gemini_client = AsyncOpenAI(
        api_key=GEMINI_API_KEY,
        base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
    )

    # Set the default OpenAI client to Gemini
    set_default_openai_client(gemini_client)
    # Disable tracing to avoid tracing errors being logged in the terminal
    set_tracing_disabled(True)

    # Create an agent configured to use the MCP server and Gemini model
    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant",
        model=OpenAIChatCompletionsModel(
            model="gemini-2.0-flash",
            openai_client=gemini_client,
        ),
        mcp_servers=[mcp_server]
    )

    return agent

async def run():
    # Start the Bright Data MCP server via npx
    async with MCPServerStdio(
        name="Bright Data web data MCP server, via npx",
        params={
            "command": "npx",
            "args": ["-y", "@brightdata/mcp"],
            "env": {
                "API_TOKEN": BRIGHT_DATA_API_TOKEN,
                "BROWSER_AUTH": BRIGHT_DATA_BROWSER_AUTH,
            }
        },
        client_session_timeout_seconds=180  # To avoid timeout errors
    ) as server:
        # Create and initialize the AI agent with the running MCP server
        agent = await create_mcp_ai_agent(server)

        # Main REPL loop to process user requests
        while True:
            # Read the user's request
            request = input("Your request -> ")

            # Exit condition
            if request.lower() == "exit":
                print("Exiting the agent...")
                break

            # Run the request through the agent
            output = await Runner.run(agent, input=request)

            # Print the result to the user
            print(f"Output -> \n{output.final_output}\n\n")

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

Apenas 81 linhas de código. E o que você obtém? Um agente de IA que pode navegar na web, contornar anti-bots, pegar dados em tempo real e falar de volta – como se isso não fosse uma grande coisa.

Graças ao novoOs protocolose ferramentas de desenvolvimento como o OpenAI Agents SDK e o Bright Data MCP, a automação de IA é agora... quase muito fácil.

Passo #7: Teste o MCP-Powered AI Agent

Execute seu agente de IA a partir do terminal com:

python agent.py

Para Linux ou macOS:

python3 agent.py

Você será recebido por um convidado amigável como:

Your request ->

Por exemplo, tente perguntar ao agente que ferramentas MCP ele tem:

What tools are you linked to through MCP?

Você receberá de volta algo como:

Como você pode ver, seu agente de IA está ciente de todas as ferramentas de MCP Bright Data que ele pode se conectar - e está pronto para usá-las!

Vamos colocar essas ferramentas de MCP brilhantes no teste final: Comande seu agente de IA para raspar alguns dados suculentos da página do Amazon P5 :

Para conseguir isso, dê uma prompt como:

From the Amazon product page "https://www.amazon.com/PlayStation%C2%AE5-console-slim-PlayStation-5/dp/B0CL61F39H/", extract the main info and return it in JSON format

Faça isso e o resultado será:

Em particular, a saída deve ser algo como:

{
  "title": "PlayStation®5 console (slim)",
  "seller_name": "Amazon.com",
  "brand": "Sony",
  "description": "The PS5 console unleashes new gaming possibilities that you never anticipated. Experience lightning fast loading with an ultra-high speed SSD, deeper immersion with support for haptic feedback, adaptive triggers, and 3D Audio*, and an all-new generation of incredible PlayStation games. Lightning Speed - Harness the power of a custom CPU, GPU, and SSD with Integrated I/O that rewrite the rules of what a PlayStation console can do. Stunning Games - Marvel at incredible graphics and experience new PS5 features. Play a back catalog of supported PS4 games. Breathtaking Immersion - Discover a deeper gaming experience with support for haptic feedback, adaptive triggers, and 3D Audio technology. Vertical stand sold separately. *3D audio via built-in TV speakers or analog/USB stereo headphones. Set up and latest system software update required.",
  "initial_price": 499,
  "currency": "USD",
  "availability": "In Stock",
  "reviews_count": 6759,
  "categories": [
    "Video Games",
    "PlayStation 5",
    "Consoles"
  ],
  "asin": "B0CL61F39H",
  "buybox_seller": "Amazon.com",
  "number_of_sellers": 1,
  "root_bs_rank": 18,
  "answered_questions": 0,
  "domain": "https://www.amazon.com/",
  "images_count": 5,
  "url": "https://www.amazon.com/PlayStation%C2%AE5-console-slim-PlayStation-5/dp/B0CL61F39H?th=1&psc=1&language=en_US&currency=USD",
  "video_count": 6,
  "image_url": "https://m.media-amazon.com/images/I/41ECK5cY-2L._SL1000_.jpg",
  "item_weight": "10.6 pounds",
  "rating": 4.7,
  "product_dimensions": "14 x 17 x 7 inches; 10.6 Pounds",
  "seller_id": "ATVPDKIKX0DER",
  "date_first_available": "December 10, 2023",
  "model_number": "CFI-2015",
  "manufacturer": "Sony",
  "department": "Video Games",
  "plus_content": true,
  "video": true,
  "final_price": 499,
  "delivery": [
    "FREE delivery Monday, May 26",
    "Or Prime members get FREE delivery Tomorrow, May 22. Order within 15 hrs 43 mins. Join Prime"
  ],
  "features": [
    "Model Number CFI-2000",
    "Includes DualSense Wireless Controller, 1TB SSD, Disc Drive, 2 Horizontal Stand Feet, HDMI Cable, AC power cord, USB cable, printed materials, ASTRO’s PLAYROOM (Pre-installed game)",
    "Vertical Stand sold separately"
  ],
  "bought_past_month": 8000,
  "is_available": true,
  "root_bs_category": "Video Games",
  "bs_category": "PlayStation  Consoles",
  "bs_rank": 15,
  "badge": "Amazon's  Choice",
  "subcategory_rank": [
    {
      "subcategory_name": "PlayStation 5 Consoles",
      "subcategory_rank": 1
    }
  ],
  "amazon_choice": true,
  "product_details": [
    {
      "type": "ASIN",
      "value": "B0CL61F39H"
    },
    {
      "type": "Release date",
      "value": "December 10, 2023"
    },
    {
      "type": "Customer Reviews",
      "value": "4.74.7 out of 5 stars6,759 ratings4.7 out of 5 stars"
    },
    {
      "type": "Best Sellers Rank",
      "value": "#18 in Video Games (See Top 100 in Video Games)#1 in PlayStation 5 Consoles"
    },
    {
      "type": "Product Dimensions",
      "value": "14 x 17 x 7 inches; 10.6 Pounds"
    },
    {
      "type": "Type of item",
      "value": "Video Game"
    },
    {
      "type": "Item model number",
      "value": "CFI-2015"
    },
    {
      "type": "Item Weight",
      "value": "10.6 pounds"
    },
    {
      "type": "Manufacturer",
      "value": "Sony"
    },
    {
      "type": "Country of Origin",
      "value": "China"
    },
    {
      "type": "Batteries",
      "value": "1 Lithium Ion batteries required. (included)"
    },
    {
      "type": "Date First Available",
      "value": "December 10, 2023"
    }
  ],
  "country_of_origin": "China",
  "seller_url": "https://www.amazon.com/sp?ie=UTF8&seller=ATVPDKIKX0DER&asin=B0CL61F39H",
  "customers_say": "Customers find the PlayStation 5 console runs well and performs mind-blowingly fast, with quick loading times and smooth game performance. The graphics quality receives positive feedback, with one customer highlighting its stunning 120Hz visuals, while the console is easy to set up with an intuitive user interface. Customers consider the price worth the investment and appreciate its pristine condition. The noise level receives mixed reviews, with some customers finding it super quiet while others report it being loud.",
  "climate_pledge_friendly": false,
  "sponsered": true,
  "store_url": "https://www.amazon.com/stores/PlayStationPlayHasNoLimits/page/5AF5EF82-86EF-4699-B450-C232B3BD720E?lp_asin=B0CL61F39H&ref_=ast_bln&store_ref=bl_ast_dp_brandLogo_sto",
  "ships_from": "Amazon.com",
  "customers_say": {
    "text": "Customers find the PlayStation 5 console runs well and performs mind-blowingly fast, with quick loading times and smooth game performance. The graphics quality receives positive feedback, with one customer highlighting its stunning 120Hz visuals, while the console is easy to set up with an intuitive user interface. Customers consider the price worth the investment and appreciate its pristine condition. The noise level receives mixed reviews, with some customers finding it super quiet while others report it being loud.",
    "keywords": {
      "positive": [
        "Functionality",
        "Gaming experience",
        "Value for money",
        "Graphics quality",
        "Quality",
        "Speed",
        "Ease of setup"
      ],
      "negative": null,
      "mixed": [
        "Noise level"
      ]
    }
  },
  "max_quantity_available": 30,
  "timestamp": "2025-05-21T10:46:13.487Z"
}

Wow! 🤯

One prompt, and you just scraped all the data from an Amazon product page.E não apenas qualquer site – a Amazon é notoriamente difícil de raspar graças a CAPTCHAs agressivas e defesas anti-bot.

Então, como isso funcionou?Por trás das cenas, o agente da IA ligou para oweb_data_amazon_productFerramenta MCP – uma das ferramentas de energia pré-construídas expostas pelo servidor MCP Bright Data. Ele lidou com o trabalho sujo: resolver CAPTCHAs, contornar a detecção de bots e pegar a mercadoria.

E não pára por aí!

Você pode usá-lo para pedir ao agente de IA para análises adicionais, criando prompts mais complexos.Afinal, o agente de IA pode escolher livremente e juntar ferramentas de seu kit de ferramentas alimentado por MCP, entãoAs possibilidades são verdadeiramente infinitas️

Com uma estrutura tão poderosa, oO mundo é seu!(Just Don't Go Full de Tony Montana)

Pensamentos finais

Agora você sabe como sobrecarregar qualquer agente de IA construído com o OpenAI Agents SDK – seja ele executado em GPT, Gemini ou qualquer outra coisa – conectando-o a um servidor MCP.

Em outras palavras, entramos no poderosoBright Data MCP serverApenas uma dasmuitos serviços que construímos para suportar fluxos de trabalho de IA do mundo real em escala.

Na Bright Data, nossa missão é simples: tornar a IA acessível a todos, em qualquer lugar.Então, até a próxima vez – fique curioso, fique ousado e continue construindo o futuro da IA com criatividade.