SDK Agen OpenAI menyediakan cara yang kuat untuk membangun aplikasi AI dengan kemampuan agen. Salah satu fitur kuncinya adalah dukungan untuk Protokol Konteks Model (MCP), yang menstandarisasi cara aplikasi memberikan konteks dan alat kepada Model Bahasa Besar (LLM). Artikel ini akan memandu Anda melalui cara menghubungkan OpenAI Agen SDK ke Server MCP, dengan langkah-langkah rinci dan contoh kode.
MCP adalah protokol terbuka yang menstandarisasi cara aplikasi memberikan konteks kepada LLM. Anggap MCP seperti "port USB-C" untuk aplikasi AI - ini menyediakan cara terstandarisasi untuk menghubungkan model AI ke berbagai sumber data dan alat. Seperti halnya USB-C menghubungkan perangkat Anda ke berbagai periferal, MCP menghubungkan model AI ke alat dan sumber data yang berbeda.
Spesifikasi MCP mendefinisikan dua jenis server berdasarkan mekanisme transportnya:
SDK Agen OpenAI menyediakan kelas yang sesuai untuk kedua jenis server ini:
MCPServerStdio untuk server stdio lokalMCPServerSse untuk server SSE jarak jauhSebelum Anda mulai, pastikan Anda telah:
Memasang Python 3.10 atau lebih tinggi
Memasang SDK Agen OpenAI:
pip install openai-agents
Untuk menggunakan server stdio lokal, Anda mungkin memerlukan alat tambahan seperti npx (untuk server MCP berbasis JavaScript)
Ayo mulai dengan menghubungkan ke server MCP stdio lokal. Kita akan menggunakan server MCP sistem berkas sebagai contoh.
Jika Anda berencana menggunakan server MCP sistem berkas, Anda akan memerlukan Node.js dan NPX:
# Pasang Node.js (jika belum terpasang)
# Untuk Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm
# Untuk macOS
brew install node
# Verifikasi pemasangan
node --version
npx --version
Buat struktur proyek dasar:
my_agent_project/
├── sample_data/
│ ├── file1.txt
│ └── file2.md
├── main.py
└── README.md
Berikut adalah contoh lengkap untuk menghubungkan ke server MCP sistem berkas menggunakan MCPServerStdio:
import asyncio
import os
import shutil
from agents import Agent, Runner, gen_trace_id, trace
from agents.mcp import MCPServerStdio
async def run_agent_with_mcp():
# Dapatkan path direktori untuk data contoh
current_dir = os.path.dirname(os.path.abspath(__file__))
sample_data_dir = os.path.join(current_dir, "sample_data")
# Buat dan konfigurasi server MCP
async with MCPServerStdio(
name="Server Sistem Berkas",
params={
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", sample_data_dir],
},
) as mcp_server:
# Buat agen yang menggunakan server MCP
agent = Agent(
name="AsistenBerita",
instructions="Gunakan alat sistem berkas untuk membaca dan menganalisis berkas-berkas di direktori sample_data.",
mcp_servers=[mcp_server]
)
# Jalankan agen dengan kueri pengguna
message = "Daftar semua berkas di direktori dan ringkas isinya."
print(f"Menjalankan kueri: {message}\\\\n")
# Hasilkan ID jejak untuk debugging
trace_id = gen_trace_id()
with trace(workflow_name="Contoh Sistem Berkas MCP", trace_id=trace_id):
print(f"Lihat jejak: <https://platform.openai.com/traces/{trace_id}\\\\n>")
result = await Runner.run(starting_agent=agent, input=message)
print(result.final_output)
if __name__ == "__main__":
# Periksa apakah npx terpasang
if not shutil.which("npx"):
raise RuntimeError("npx tidak terpasang. Silakan pasang dengan `npm install -g npx`.")
asyncio.run(run_agent_with_mcp())
Dalam contoh ini:
MCPServerStdio yang menjalankan server MCP sistem berkas sebagai subproses.Agent melalui parameter mcp_servers.list_tools() pada server MCP untuk membuat LLM mengetahui alat yang tersedia.call_tool() pada server.Sekarang mari kita lihat bagaimana menghubungkan ke server MCP jarak jauh menggunakan SSE:
Server MCP SSE (Event yang Dikirim oleh Server) berjalan secara jarak jauh dan mengekspos fungsionalitas mereka melalui endpoint HTTP. Tidak seperti server stdio, mereka tidak berjalan sebagai subproses dari aplikasi Anda.
Berikut adalah kode contoh yang menghubungkan ke server MCP SSE:
import asyncio
from agents import Agent, Runner, gen_trace_id, trace
from agents.mcp import MCPServerSse
from agents.model_settings import ModelSettings
async def run_agent_with_remote_mcp():
# Buat dan konfigurasi koneksi server MCP SSE
async with MCPServerSse(
name="Layanan Cuaca",
params={
"url": "<https://example.com/mcp/sse>",
# Parameter otentikasi opsional
"headers": {
"Authorization": "Bearer your_api_key_here"
}
},
) as mcp_server:
# Buat agen menggunakan server MCP jarak jauh
agent = Agent(
name="AsistenCuaca",
instructions="Gunakan alat cuaca untuk menjawab pertanyaan tentang kondisi cuaca saat ini.",
mcp_servers=[mcp_server],
# Memaksa agen menggunakan alat ketika tersedia
model_settings=ModelSettings(tool_choice="required")
)
# Jalankan agen dengan kueri pengguna
message = "Bagaimana cuaca di Tokyo hari ini?"
print(f"Menjalankan kueri: {message}\\\\n")
trace_id = gen_trace_id()
with trace(workflow_name="Contoh MCP Cuaca", trace_id=trace_id):
print(f"Lihat jejak: <https://platform.openai.com/traces/{trace_id}\\\\n>")
result = await Runner.run(starting_agent=agent, input=message)
print(result.final_output)
if __name__ == "__main__":
asyncio.run(run_agent_with_remote_mcp())
Untuk benar-benar memahami cara kerja MCP, akan membantu untuk mengimplementasikan server MCP yang sederhana. Berikut contoh server MCP SSE minimal:
import asyncio
import json
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from typing import Dict, Any, List, Optional
app = FastAPI()
# Definisikan alat yang akan disediakan oleh server MCP kita
TOOLS = [
{
"type": "function",
"function": {
"name": "add",
"description": "Menambahkan dua angka bersama",
"parameters": {
"type": "object",
"properties": {
"a": {"type": "number", "description": "Angka pertama"},
"b": {"type": "number", "description": "Angka kedua"}
},
"required": ["a", "b"]
}
}
},
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Dapatkan cuaca untuk suatu lokasi",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "Nama kota"}
},
"required": ["location"]
}
}
}
]
# Implementasikan fungsionalitas alat yang sebenarnya
async def call_tool(tool_name: str, parameters: Dict[str, Any]) -> Dict[str, Any]:
if tool_name == "add":
return {"result": parameters["a"] + parameters["b"]}
elif tool_name == "get_weather":
# Dalam implementasi nyata, Anda akan memanggil API cuaca yang sebenarnya
weather_data = {
"Tokyo": {"condition": "Cerah", "temperature": 25},
"New York": {"condition": "Berawan", "temperature": 18},
"London": {"condition": "Hujan", "temperature": 15}
}
location = parameters["location"]
if location in weather_data:
return {"weather": weather_data[location]}
return {"error": f"Data cuaca tidak tersedia untuk {location}"}
return {"error": f"Alat tidak dikenal: {tool_name}"}
async def sse_event_generator(request: Request):
# Baca badan permintaan
body_bytes = await request.body()
body = json.loads(body_bytes)
# Tangani berbagai operasi MCP
if body["action"] == "list_tools":
yield f"data: {json.dumps({'tools': TOOLS})}\\\\n\\\\n"
elif body["action"] == "call_tool":
tool_name = body["tool_name"]
parameters = body["parameters"]
result = await call_tool(tool_name, parameters)
yield f"data: {json.dumps({'result': result})}\\\\n\\\\n"
@app.post("/sse")
async def sse_endpoint(request: Request):
return StreamingResponse(
sse_event_generator(request),
media_type="text/event-stream"
)
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
Untuk meningkatkan kinerja, Anda dapat menyimpan daftar alat dari server MCP:
# Buat server MCP dengan penyimpanan alat
async with MCPServerSse(
name="Layanan Cuaca",
params={"url": "<https://example.com/mcp/sse>"},
cache_tools_list=True # Aktifkan penyimpanan
) as mcp_server:
# Gunakan server seperti sebelumnya...
Ketika cache_tools_list=True diatur, SDK hanya akan memanggil list_tools() pada server MCP sekali dan menggunakan kembali hasilnya untuk jalannya agen berikutnya. Ini mengurangi latensi, terutama untuk server jarak jauh.
Untuk membatalkan penyimpanan jika diperlukan:
mcp_server.invalidate_tools_cache()
SDK Agen OpenAI menyertakan kemampuan pelacakan bawaan yang secara otomatis menangkap operasi MCP:
Anda dapat melihat jejak ini di https://platform.openai.com/traces/ ketika Anda menggunakan pengelola konteks trace seperti yang ditunjukkan dalam contoh di atas.
Anda dapat menghubungkan agen Anda ke beberapa server MCP secara bersamaan, memberinya akses ke berbagai alat yang lebih luas:
async def run_with_multiple_servers():
async with MCPServerStdio(
name="Sistem Berkas",
params={"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]}
) as fs_server, MCPServerSse(
name="API Cuaca",
params={"url": "<https://example.com/weather/mcp/sse>"}
) as weather_server:
# Buat agen dengan kedua server MCP
agent = Agent(
name="AsistenMultiAlat",
instructions="Gunakan semua alat yang tersedia untuk membantu pengguna.",
mcp_servers=[fs_server, weather_server]
)
# Jalankan agen
result = await Runner.run(
starting_agent=agent,
input="Pertama, periksa cuaca di Tokyo, lalu baca isi dari berkas report.txt."
)
print(result.final_output)
Ketika bekerja dengan server MCP, Anda mungkin mengalami berbagai masalah. Berikut adalah beberapa masalah umum dan cara mengatasinya:
Jika server MCP Anda tidak merespons:
try:
async with MCPServerSse(
name="Layanan Cuaca",
params={"url": "<https://example.com/mcp/sse>"}
) as mcp_server:
# Gunakan server...
except Exception as e:
print(f"Gagal terhubung ke server MCP: {e}")
# Implementasikan strategi cadangan
Ketika eksekusi alat gagal, tangani dengan baik:
try:
result = await Runner.run(starting_agent=agent, input=user_query)
print(result.final_output)
except Exception as e:
print(f"Kesalahan selama eksekusi agen: {e}")
# Anda mungkin ingin memeriksa log jejak untuk informasi kesalahan yang lebih rinci
Dukungan SDK Agen OpenAI untuk MCP memungkinkan Anda memperluas agen Anda dengan berbagai alat dan kemampuan. Apakah Anda menggunakan server stdio lokal atau endpoint SSE jarak jauh, integrasinya sederhana dan kuat.
Dengan menghubungkan ke server MCP, agen Anda dapat mengakses sistem berkas, API cuaca, basis data, dan hampir semua alat eksternal atau sumber data yang mengekspos antarmuka MCP. Fleksibilitas ini menjadikan SDK Agen OpenAI dasar yang kuat untuk membangun aplikasi AI yang canggih.
Ingatlah untuk memanfaatkan fitur seperti penyimpanan alat untuk mengoptimalkan kinerja, dan gunakan kemampuan pelacakan bawaan untuk mendebug dan memantau interaksi agen Anda dengan server MCP.
Selamat coding dengan OpenAI Agents dan MCP!
