OpenAI Agents SDK là framework Python để xây dựng agent có tool, handoff và guardrail. Tài liệu của SDK mô tả cách cắm các provider không phải OpenAI. Với một API tương thích OpenAI như BroadNet Inference, bạn đưa cho SDK client AsyncOpenAI của riêng mình và dùng lớp model Chat Completions. Mặc định SDK dùng Responses API, thứ mà nhiều provider không phục vụ.
Thiết lập
- Cài SDK. SDK cần Python 3.10 trở lên.
pip install openai-agents
export BROADNET_API_KEY='your-broadnet-key'
- Tạo client, model và agent.
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())
- Chạy thử. Agent sẽ gọi
get_order_statusvà trả lời dựa trên kết quả của nó.
Ba cách nối provider
Tài liệu SDK liệt kê các lựa chọn có sẵn sau:
- Theo từng agent: truyền
OpenAIChatCompletionsModellàmAgent.model, như ví dụ trên. Dùng cách này khi các agent khác nhau dùng các provider khác nhau. - Mặc định toàn cục:
set_default_openai_client(client)biến client của bạn thành mặc định. Dùng kèmset_default_openai_api("chat_completions"). - Theo từng lần chạy: truyền một
ModelProvidertùy chỉnh vàoRunConfig(model_provider=...).
Cách mặc định toàn cục trông như sau:
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")
Nếu chỉ dùng biến môi trường, hãy đặt OPENAI_BASE_URL=https://inference.broadnet.ai/v1 và đặt OPENAI_API_KEY là key BroadNet, rồi gọi set_default_openai_api và set_tracing_disabled giống như trên.
Theo tài liệu SDK, khi định tuyến qua Chat Completions, SDK lặng lẽ bỏ các trường chỉ có ở Responses, như previous_response_id, conversation_id và prompt. Muốn nhận lỗi thay vì vậy, hãy đặt strict_feature_validation=True trên OpenAIProvider. Hãy tự giữ trạng thái hội thoại trong code của bạn, ví dụ truyền danh sách đầu vào của kết quả trước vào lần chạy tiếp theo. Các tool do OpenAI host như web search và file search không có ở provider khác. Hãy dùng function_tool cho mọi thứ agent cần gọi.
Tracing
Tracing bật sẵn và gửi trace về OpenAI. Tài liệu SDK nói rằng nếu không có API key từ platform.openai.com, bạn nên tắt nó bằng set_tracing_disabled() hoặc thiết lập một tracing processor khác. Nếu bạn có key OpenAI, bạn có thể giữ tracing và truyền key đó bằng set_tracing_export_api_key(...). SDK chỉ dùng key này để tải trace lên. Key BroadNet không dùng được cho việc này.
Nên chọn model nào
| Loại agent | Model | Ghi chú |
|---|---|---|
| Agent dùng tool | GLM 5.3 | Có ghi hỗ trợ tool và đầu ra có cấu trúc; context 1M |
| Đầu vào hình ảnh, có tool | Qwen3.8 27B | Context 262K; đã thử nghiệm bằng tiếng Ả Rập |
| Agent chạy lâu với giá cố định | DeepSeek V4.1 Flash | Gói không giới hạn; BroadNet không ghi hỗ trợ tool |
Tài liệu SDK cảnh báo rằng một số provider không hỗ trợ đầu ra có cấu trúc theo JSON schema. Nếu bạn đặt output_type cho agent, hãy dùng GLM 5.3 hoặc Qwen3.8 27B. So sánh giá trên trang bảng giá.
Xử lý sự cố
- 401. Key BroadNet bị sai, hết hạn hoặc hết hạn mức trả theo mức dùng. Lỗi tracing trong log là chuyện khác: chúng nghĩa là tracing vẫn đang bật mà không có key OpenAI.
- 404 hoặc “not found”. Nhiều khả năng bạn đang dùng Responses API. Hãy dùng
OpenAIChatCompletionsModelhoặcset_default_openai_api("chat_completions"). Nếu đã đặt rồi, kiểm tra model ID có khớp chính xác với ID của BroadNet không. Các model trả phí cần nạp tiền; tín dụng $5 dùng được cho Gemma 4 VL 26B và hai model Transcribe. final_outputrỗng. Phần suy luận được tính vàomax_tokens. Nếu bạn đặtModelSettings(max_tokens=...), hãy tăng giá trị lên. Vì sao câu trả lời trả về rỗng.- 429. Key trả theo mức dùng cho phép 30 request mỗi phút và 4 request cùng lúc. Mỗi vòng gọi tool là một request mới. Xem lỗi và thử lại.
- Agent song song trên một gói. Một phiên của gói không giới hạn chạy một request tại một thời điểm. Các agent khởi chạy cùng lúc bằng
asyncio.gathercần mỗi agent một phiên, nếu không chúng sẽ phải xếp hàng. Xem chạy agent song song với giá cố định.
