OpenAI Agents SDK; araçlar, devirler (handoffs) ve korkuluklar (guardrails) içeren ajanlar için bir Python çerçevesidir. Belgeleri, OpenAI dışı sağlayıcıların nasıl bağlanacağını anlatır. BroadNet Inference gibi OpenAI uyumlu bir API için SDK’ya kendi AsyncOpenAI istemcinizi verir ve Chat Completions model sınıfını kullanırsınız. SDK varsayılan olarak Responses API’yi kullanır; pek çok sağlayıcı ise bu API’yi sunmaz.
Kurulum
- SDK’yı kurun. Python 3.10 veya daha yenisi gerekir.
pip install openai-agents
export BROADNET_API_KEY='your-broadnet-key'
- İstemciyi, modeli ve ajanı oluşturun.
import asyncio
import os
from agents import (
Agent,
AsyncOpenAI,
OpenAIChatCompletionsModel,
Runner,
function_tool,
set_tracing_disabled,
)
set_tracing_disabled(disabled=True) # tracing needs a platform.openai.com key
client = AsyncOpenAI(
base_url="https://inference.broadnet.ai/v1",
api_key=os.environ["BROADNET_API_KEY"],
)
model = OpenAIChatCompletionsModel(model="broadnet/glm-5.3", openai_client=client)
@function_tool
def get_order_status(order_id: str) -> str:
"""Look up an order."""
return f"Order {order_id}: shipped"
agent = Agent(
name="Support agent",
instructions="Answer briefly. Use tools when you need order data.",
model=model,
tools=[get_order_status],
)
async def main():
result = await Runner.run(agent, "Where is order 4471?")
print(result.final_output)
asyncio.run(main())
- Çalıştırın. Ajan
get_order_statusaracını çağırmalı ve yanıtını bu aracın sonucuna dayandırmalıdır.
Sağlayıcıyı bağlamanın üç yolu
SDK belgeleri şu yerleşik seçenekleri listeler:
- Ajan başına: yukarıdaki gibi
OpenAIChatCompletionsModel’iAgent.modelolarak verin. Farklı ajanlar farklı sağlayıcılar kullanıyorsa bunu tercih edin. - Genel varsayılan:
set_default_openai_client(client)istemcinizi varsayılan yapar. Bunuset_default_openai_api("chat_completions")ile birlikte kullanın. - Çalıştırma başına:
RunConfig(model_provider=...)içinde özel birModelProviderverin.
Genel varsayılan şöyle görünür:
import os
from agents import (
Agent,
AsyncOpenAI,
set_default_openai_api,
set_default_openai_client,
set_tracing_disabled,
)
client = AsyncOpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
set_default_openai_client(client, use_for_tracing=False)
set_default_openai_api("chat_completions")
set_tracing_disabled(True)
agent = Agent(name="Assistant", instructions="Be brief.", model="broadnet/glm-5.3")
Yalnızca ortam değişkenleriyle çalışacaksanız OPENAI_BASE_URL=https://inference.broadnet.ai/v1 ayarlayın ve OPENAI_API_KEY değişkenine BroadNet anahtarınızı yazın; ardından aynı set_default_openai_api ve set_tracing_disabled çağrılarını yapın.
SDK belgelerine göre Chat Completions üzerinden yönlendirdiğinizde SDK, yalnızca Responses’a özgü previous_response_id, conversation_id ve prompt gibi alanları sessizce düşürür. Bunun yerine hata almak için OpenAIProvider üzerinde strict_feature_validation=True ayarlayın. Konuşma durumunu kendi kodunuzda tutun; örneğin önceki sonucun girdi listesini bir sonraki çalıştırmaya aktarın. Web araması ve dosya araması gibi OpenAI’nin barındırdığı araçlar başka sağlayıcılarda yoktur. Ajanın çağırması gereken her şey için function_tool kullanın.
Tracing
Tracing varsayılan olarak açıktır ve izleri OpenAI’ye gönderir. SDK belgeleri, platform.openai.com’dan alınmış bir API anahtarınız yoksa tracing’i set_tracing_disabled() ile kapatmanızı ya da farklı bir tracing işlemcisi kurmanızı söyler. Bir OpenAI anahtarınız varsa tracing’i açık bırakıp bu anahtarı set_tracing_export_api_key(...) ile verebilirsiniz. SDK onu yalnızca izleri yüklemek için kullanır. BroadNet anahtarınız bu iş için çalışmaz.
Hangi modeli seçmeli
| Ajan türü | Model | Notlar |
|---|---|---|
| Araç kullanan ajanlar | GLM 5.3 | Araçlar ve yapılandırılmış çıktı listeleniyor; 1M bağlam |
| Araçlarla görsel girdi | Qwen3.8 27B | 262K bağlam; Arapçada test edildi |
| Sabit fiyatla uzun süre çalışan ajanlar | DeepSeek V4.1 Flash | Sınırsız planlar; araçlar BroadNet tarafından listelenmiyor |
SDK belgeleri, bazı sağlayıcıların JSON şemalı yapılandırılmış çıktıları desteklemediği konusunda uyarır. Bir ajanda output_type ayarlıyorsanız GLM 5.3 veya Qwen3.8 27B kullanın. Fiyatları fiyatlandırma sayfasında karşılaştırın.
Sorun giderme
- 401. BroadNet anahtarı yanlış, süresi dolmuş veya kullandıkça öde hakkı tükenmiş. Günlüklerdeki tracing hataları ayrı bir konudur: tracing’in OpenAI anahtarı olmadan hâlâ açık olduğunu gösterir.
- 404 veya “not found”. Büyük olasılıkla Responses API’yi kullanıyorsunuz.
OpenAIChatCompletionsModelya daset_default_openai_api("chat_completions")kullanın. Bu zaten ayarlıysa model kimliğinin BroadNet’inkiyle birebir aynı olduğunu kontrol edin. Ücretli modeller bakiye yüklemesi gerektirir; $5 kredi yalnızca Gemma 4 VL 26B modelini kapsar. - Boş
final_output. Akıl yürütmemax_tokenssınırına dahildir.ModelSettings(max_tokens=...)ayarladıysanız değeri yükseltin. Yanıtlar neden boş geliyor. - 429. Kullandıkça öde anahtarı dakikada 30 isteğe ve aynı anda 4 isteğe izin verir. Her araç gidiş-dönüşü yeni bir istektir. Hatalar ve yeniden denemeler rehberine bakın.
- Bir planda paralel ajanlar. Bir sınırsız plan oturumu aynı anda tek istek çalıştırır.
asyncio.gatherile birlikte başlatılan ajanların her biri ayrı bir oturum ister, aksi halde sıraya girerler. Sabit fiyatla paralel ajan çalıştırma yazısına bakın.
