Trong những ứng dụng Generative AI đầu tiên, kiến trúc thường khá đơn giản. Application nhận câu hỏi của người dùng, gửi nội dung tới một Large Language Model và hiển thị câu trả lời được tạo ra.

Cách tiếp cận đó rất phù hợp với chatbot, summarization, content generation hoặc những AI feature tương đối ngắn.

AI Agents đặt ra một bài toán khác.

Một Agent có thể nhận yêu cầu: “Kiểm tra khách hàng này, tìm các đơn hàng gần nhất, xác định vấn đề đang xảy ra và nếu cần thì tạo ticket cho bộ phận hỗ trợ.”

Để hoàn thành yêu cầu đó, model có thể phải gọi nhiều tools, quan sát kết quả của từng tool, quyết định bước tiếp theo, chuyển nhiệm vụ cho một Agent chuyên môn khác, chờ một con người phê duyệt action nhạy cảm và chỉ kết thúc khi nhiệm vụ thực sự hoàn thành.

Lúc này application không còn đơn giản là một API call tới model.

Nó cần một Agent Runtime.

OpenAI Agents SDK được xây cho chính lớp bài toán đó. OpenAI mô tả SDK như một package tương đối nhẹ với ít abstraction, nhưng đủ để xây các agentic applications thực tế. SDK phát triển từ những thử nghiệm trước đó với Swarm và hiện được định vị như một runtime production-ready cho Agent workflows. Các primitive cốt lõi gồm Agents, Tools, Agents-as-Tools hoặc Handoffs và Guardrails; phía trên đó là Agent loop, Sessions, Human-in-the-loop, Tracing, MCP, Sandbox Agents, Realtime Agents và nhiều capability khác.

Đây là điểm quan trọng để hiểu đúng Agents SDK.

Nó không đơn thuần là một thư viện giúp viết prompt dễ hơn.

Nó là một lớp orchestration nằm giữa model và software system, chịu trách nhiệm quản lý nhiều bước trong quá trình Agent suy luận và hành động.

Tài liệu hiện tại của SDK đã mở rộng đáng kể so với những phiên bản đầu. Ngoài text Agent thông thường, OpenAI còn hỗ trợ Sandbox Agents có workspace riêng, Realtime Agents cho các ứng dụng độ trễ thấp, Voice Pipelines, deterministic testing utilities, usage accounting, durable execution integrations và nhiều cơ chế quản lý state.

Bài viết này được xây theo một mục tiêu khác với tutorial thông thường.

Thay vì chỉ hướng dẫn tạo một Agent trong vài phút, mục tiêu là đọc toàn bộ Agents SDK như một kiến trúc phần mềm, hiểu lý do từng primitive tồn tại, chúng liên kết với nhau như thế nào và đâu là những phần thực sự quan trọng khi đưa Agent từ prototype lên production.

Mục lục

OpenAI Agents SDK là gì?
Vì sao cần Agents SDK khi đã có Responses API?
Mental Model quan trọng nhất của Agents SDK
Cài đặt và Agent đầu tiên
Agent: đơn vị cơ bản của hệ thống
Instructions, Dynamic Instructions và Prompt
Models và Model Settings
Runner: nơi Agent thực sự bắt đầu chạy
Agent Loop hoạt động như thế nào?
Max Turns và điều kiện kết thúc Agent
RunResult: đừng chỉ nhìn final_output
Streaming và trải nghiệm real-time
Tools: biến model từ người trả lời thành người hành động
Function Tools
Hosted Tools
Tool Search và vấn đề Tool Explosion
Programmatic Tool Calling
Agents as Tools
Handoffs
Agents-as-Tools và Handoffs khác nhau ở đâu?
Agent Orchestration bằng LLM và bằng Code
Structured Outputs
Context Management
Local Context và LLM Context khác nhau thế nào?
Sessions và Conversation Memory
Sessions khác Business State như thế nào?
Guardrails
Tool Guardrails và Security Boundary
Human-in-the-loop
RunState và khả năng Pause/Resume
Model Context Protocol
Hosted MCP và Local MCP
Tool Filtering, Approval và MCP Security
Sandbox Agents
Khi nào cần Sandbox thay vì Tool?
Tracing và Observability
Usage Tracking và Cost Control
Testing Agent Workflows
Agent Visualization
Realtime Agents
Voice Pipelines
Durable Execution
OpenAI Agents SDK và Multi-Agent Systems
Một kiến trúc Production tham khảo
Case Study: Enterprise Customer Service Agent
Những lỗi phổ biến khi sử dụng Agents SDK
Khi nào không nên dùng Agents SDK?
Roadmap học OpenAI Agents SDK
Agents SDK tiết lộ điều gì về tương lai Agent Engineering?
Kết luận
Tài liệu tham khảo

1. OpenAI Agents SDK là gì?

OpenAI Agents SDK là một framework dành cho việc xây dựng agentic applications bằng Python và TypeScript.

Trong Python, package có thể được cài bằng:

pip install openai-agents

SDK được thiết kế quanh một số primitive nhỏ thay vì bắt developer phải học một abstraction graph hoặc domain-specific language quá phức tạp. OpenAI nhấn mạnh hai nguyên tắc thiết kế: cung cấp đủ capability để đáng sử dụng nhưng vẫn giữ số primitive ở mức nhỏ, đồng thời hoạt động tốt với default configuration nhưng vẫn cho phép developer tùy biến khi cần.

Ở mức đơn giản nhất, một Agent có thể chỉ gồm:

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant."
)

result = Runner.run_sync(
    agent,
    "Explain what an AI agent is."
)

print(result.final_output)

Nhìn vào đoạn code này rất dễ nghĩ Agents SDK chỉ là một wrapper quanh model API.

Thực tế phần quan trọng nằm trong:

Runner.run_sync(...)

Runner không chỉ gọi model một lần.

Nó có khả năng tiếp tục chạy model, thực thi tools, xử lý handoffs, guardrails và nhiều thành phần khác cho đến khi đạt điều kiện kết thúc.

Vì vậy có thể xem Agents SDK gồm hai lớp lớn.

Agent mô tả Agent là ai và có những capability gì.

Runner quyết định Agent được thực thi như thế nào.

Hai abstraction này là nền móng để hiểu gần như toàn bộ SDK.

2. Vì sao cần Agents SDK khi đã có Responses API?

Đây là một câu hỏi quan trọng.

OpenAI đã có Responses API với khả năng model generation, tools và nhiều capability khác. Vậy tại sao cần thêm Agents SDK?

Câu trả lời nằm ở orchestration.

Responses API cung cấp lower-level primitives để application tương tác với model.

Agents SDK cung cấp một runtime cao hơn để quản lý vòng đời của Agent.

OpenAI khuyến nghị dùng Responses API trực tiếp khi application muốn tự sở hữu agent loop, tool dispatch và state management, hoặc khi workflow ngắn và chủ yếu chỉ cần model response.

Agents SDK phù hợp hơn khi developer muốn runtime quản lý nhiều turns, tool execution, guardrails, handoffs, sessions hoặc các nhiệm vụ có workspace và resumable execution.

Điểm quan trọng là đây không phải lựa chọn “một trong hai” cho toàn bộ hệ thống.

Một application có thể dùng Agents SDK cho một workflow phức tạp nhưng vẫn gọi Responses API trực tiếp ở những đoạn cần control thấp hơn.

Điều này khá giống sự khác biệt giữa sử dụng SQL trực tiếp và sử dụng một higher-level application framework.

Framework giúp giảm lượng infrastructure code developer phải tự xây.

Nhưng đổi lại, runtime sở hữu nhiều behavior hơn.

3. Mental Model quan trọng nhất của Agents SDK

Có thể hiểu runtime bằng một flow duy nhất:

Input → Model → Tool hoặc Handoff → Observation → Model tiếp tục → Final Output

Runner gọi model với Agent hiện tại và input hiện tại. Nếu model tạo final output mà không yêu cầu tool, run kết thúc. Nếu model yêu cầu tool, SDK thực thi tool, thêm result vào context rồi gọi model tiếp. Nếu model yêu cầu handoff, Agent hiện tại được thay bằng Agent mới và vòng lặp tiếp tục.

Đây chính là Agent Loop.

Một chatbot truyền thống thường có một model invocation cho mỗi user turn.

Một Agent run có thể chứa nhiều model invocations trong cùng một logical user turn.

Ví dụ user nói:

Kiểm tra đơn hàng A100 và cho tôi biết khi nào giao.

Một run có thể thực hiện:

Model nhận yêu cầu.
Model gọi get_order("A100").
Tool trả tracking ID.
Model nhận thấy cần thêm dữ liệu.
Model gọi get_tracking_status(...).
Tool trả estimated delivery.
Model tạo final answer.

Với user, đây chỉ là một câu hỏi.

Với runtime, đó là nhiều bước execution.

Đây là lý do Agents SDK không nên được nhìn như một model client.

Nó là workflow runtime cho model-driven execution.

4. Cài đặt và Agent đầu tiên

Quickstart chính thức bắt đầu bằng virtual environment:

python -m venv .venv

Sau đó cài SDK:

pip install openai-agents

và thiết lập OPENAI_API_KEY.

OpenAI sử dụng virtual environment trong quickstart vì đây là cách phù hợp để tách dependency của từng project.

Một Agent tối thiểu chỉ cần name.

Trong thực tế nên có instructions.

from agents import Agent

agent = Agent(
    name="Customer Service",
    instructions=(
        "You help customers with order and support questions. "
        "Never invent order information."
    )
)

Sau đó chạy:

from agents import Runner

result = await Runner.run(
    agent,
    "Where is my order?"
)

SDK trả về RunResult, không phải chỉ một chuỗi.

Đây là chi tiết đáng chú ý.

Agent application production gần như luôn cần nhiều thông tin hơn final text.

5. Agent: đơn vị cơ bản của hệ thống

Trong Agents SDK, Agent là building block trung tâm.

OpenAI định nghĩa Agent là LLM được cấu hình với instructions, tools và những runtime behaviors tùy chọn như handoffs, guardrails và structured outputs.

Một Agent có thể bao gồm các thành phần như:

Thành phần	Vai trò
`name`	Tên Agent
`instructions`	Hướng dẫn hành vi
`model`	Model được sử dụng
`model_settings`	Cấu hình model
`tools`	Capability Agent có thể gọi
`handoffs`	Agent khác mà nó có thể chuyển giao
`input_guardrails`	Kiểm tra input
`output_guardrails`	Kiểm tra output
`output_type`	Structured output schema
`mcp_servers`	MCP servers cung cấp tools
`hooks`	Lifecycle callbacks

Điều đáng chú ý là Agent definition mang cả hai loại concern.

Một phần là AI configuration như model và instructions.

Một phần là software runtime configuration như tools, handoffs và hooks.

Đây chính là lý do Agentic Engineering nằm giữa AI và Software Engineering.

6. Instructions, Dynamic Instructions và Prompt

Instructions gần tương đương với system-level guidance của Agent.

Một implementation đơn giản:

agent = Agent(
    name="Financial Analyst",
    instructions=(
        "Analyze financial data conservatively. "
        "Distinguish facts from hypotheses."
    )
)

Nhưng production systems thường cần dynamic instructions.

Ví dụ Agent có thể cần biết tenant hiện tại, loại user hoặc workflow hiện tại.

OpenAI cho phép instructions được tạo động thông qua callback, và Agent definition cũng hỗ trợ prompt configuration từ Responses API.

Một sai lầm phổ biến là đưa mọi business data vào instructions.

Instructions nên định nghĩa behavior tương đối ổn định.

Dynamic business data thường phù hợp hơn với context hoặc tools.

Ví dụ policy:

Không bao giờ tạo refund trực tiếp trên 10 triệu.

có thể nằm trong instructions để model hiểu.

Nhưng security enforcement không nên chỉ nằm ở instructions.

Tool hoặc application layer vẫn phải kiểm tra rule đó.

Prompt là guidance.

Không phải authorization boundary.

7. Models và Model Settings

Agents SDK hỗ trợ OpenAI models thông qua Responses API và cũng có lớp hỗ trợ Chat Completions, providers khác và custom model implementations. Responses API là hướng được OpenAI khuyến nghị cho các ứng dụng OpenAI-native.

Một Agent có thể chỉ định model:

agent = Agent(
    name="Research Agent",
    model="gpt-5.6-sol",
    instructions="Research carefully."
)

Hoặc application có thể override model ở cấp RunConfig.

Điểm đáng chú ý là SDK cho phép mix nhiều model trong một workflow.

Ví dụ triage có thể dùng model nhanh và rẻ, trong khi một Agent chuyên phân tích sâu dùng model mạnh hơn.

Đây là một pattern production quan trọng.

Không phải mọi bước đều cần frontier intelligence.

Một classification đơn giản không nhất thiết phải dùng cùng model với một complex investigation.

Agentic architecture tốt phải nghĩ tới cả capability lẫn economics.

8. Runner: nơi Agent thực sự bắt đầu chạy

Runner là runtime điều khiển Agent loop.

Có ba phương thức chính:

await Runner.run(...)

cho async execution,

Runner.run_sync(...)

cho synchronous execution,

và:

Runner.run_streamed(...)

cho streaming.

run_sync() về bản chất gọi async runtime bên dưới.

Trong backend production, async thường tự nhiên hơn vì Agent có thể phải chờ nhiều I/O như model requests, APIs, database hoặc external tools.

Runner nhận:

starting agent;
input;
optional context;
run configuration;
session;
hooks;
state khi resume.

Điều này cho thấy Runner không chỉ đơn giản là một executor.

Nó là lifecycle manager của toàn bộ Agent run.

9. Agent Loop hoạt động như thế nào?

Theo tài liệu chính thức, Runner loop có ba outcome chính sau mỗi model call.

Nếu output được xem là final output, loop kết thúc.

Nếu model yêu cầu handoff, Agent hiện tại thay đổi và loop tiếp tục.

Nếu model tạo tool calls, SDK thực hiện tools, đưa results vào input rồi tiếp tục gọi model.

Một chi tiết rất quan trọng là final output không chỉ có nghĩa:

Model đã tạo text.

Model có thể tạo text cùng tool call.

Run chỉ thực sự hoàn thành khi runtime xác định output đã đáp ứng điều kiện final và không còn action cần thực hiện.

Điều này giải thích tại sao application không nên tự parse từng response model nếu đã giao orchestration cho Runner.

Runner đang giữ state machine của Agent.

10. Max Turns và điều kiện kết thúc Agent

Agent loop tạo ra một rủi ro tự nhiên:

Model có thể tiếp tục gọi tools hoặc handoff quá nhiều lần.

Runner hỗ trợ max_turns để giới hạn số vòng model execution. Nếu vượt quá giới hạn, SDK raise MaxTurnsExceeded.

Đây không chỉ là một cấu hình kỹ thuật.

Nó là một cost và reliability control.

Một Agent production không nên mặc định có khả năng suy luận vô hạn.

Một support Agent nếu cần 40 model turns để trả lời một câu hỏi đơn giản có thể đang có vấn đề về architecture.

Một giới hạn turns hợp lý giúp phát hiện loop, tool confusion hoặc prompt design yếu.

11. RunResult: đừng chỉ nhìn final_output

Sau một run, SDK trả RunResult hoặc RunResultStreaming.

Nhiều tutorial chỉ sử dụng:

result.final_output

nhưng production application nên hiểu toàn bộ result surface.

RunResultBase bao gồm những thông tin như:

final_output;
new_items;
last_agent;
raw_responses;
to_input_list();
last_response_id;
guardrail results;
interruptions;
resumable state.

new_items đặc biệt hữu ích vì nó chứa rich run items liên quan tới Agent, tool, handoff và approvals.

last_agent cho biết Agent nào cuối cùng sở hữu cuộc hội thoại.

to_input_list() giúp tạo transcript có thể sử dụng cho turn tiếp theo nếu application tự quản history.

to_state() quan trọng cho pause/resume workflows.

Một Agent application tốt thường phải quan sát nhiều hơn final answer.

12. Streaming và trải nghiệm real-time

Runner.run_streamed() cho phép application nhận event trong lúc Agent đang chạy.

result = Runner.run_streamed(
    agent,
    "Investigate this issue"
)

async for event in result.stream_events():
    ...

SDK có cả raw model events và higher-level run item events.

Streaming không chỉ để tạo hiệu ứng chữ chạy trên UI.

Một Agent có thể mất nhiều giây hoặc vài phút.

UI có thể hiển thị:

Agent đang search;
tool vừa được gọi;
Agent đã chuyển sang specialist;
partial answer;
approval đang chờ.

Một chi tiết quan trọng trong docs là run chưa thực sự hoàn thành chỉ vì token cuối cùng đã xuất hiện. Session persistence, approval bookkeeping hoặc history compaction vẫn có thể tiếp tục sau visible output cuối. Application nên consume stream tới khi iterator hoàn tất.

Đây là loại chi tiết rất dễ bị bỏ qua khi chuyển từ demo sang production.

13. Tools: biến model từ người trả lời thành người hành động

Nếu Agent là LLM có instructions, Tools là thứ biến nó thành một system có khả năng tương tác với environment.

Agents SDK hiện hỗ trợ nhiều nhóm tool:

OpenAI-hosted tools;
local/runtime tools;
Function Tools;
Agents as Tools;
experimental Codex tool.

Hosted tools hiện bao gồm những capability như web search, file search, code interpreter, hosted MCP và image generation. SDK cũng có Tool Search để giảm tool surface và Programmatic Tool Calling để model điều phối nhiều tools thông qua generated JavaScript trong những trường hợp phù hợp.

Đây là một bước tiến đáng kể so với function calling thế hệ đầu.

Tool system hiện đã trở thành một capability platform.

14. Function Tools

Function Tool là cách trực tiếp nhất để đưa business logic vào Agent.

Ví dụ:

from agents import Agent, Runner
from agents.decorators import tool

@tool
def get_order_status(order_id: str) -> str:
    """Return the current status of an order."""
    return f"Order {order_id} is being shipped."

agent = Agent(
    name="Order Assistant",
    instructions="Help customers with their orders.",
    tools=[get_order_status]
)

SDK tạo schema cho function để model hiểu tên tool, arguments và expected behavior. Tool inputs được validate bằng hệ thống type/schema của Python và Pydantic.

Tool description rất quan trọng.

Docstring:

Return the current status of an order.

không chỉ dành cho developer.

Nó là thông tin model dùng để quyết định khi nào gọi tool.

Vì vậy Tool Design cũng là Prompt Design.

Nhưng ở một abstraction chặt chẽ hơn.

15. Hosted Tools

Một số capability không cần developer tự triển khai function.

OpenAI-hosted tools có thể được thực thi trong infrastructure của OpenAI khi sử dụng Responses-based model.

Ví dụ:

Web Search;
File Search;
Code Interpreter;
Hosted MCP;
Image Generation.

Điều này giảm đáng kể infrastructure code.

Ví dụ thay vì tự xây search API integration, Agent có thể được cấp WebSearchTool.

Tuy nhiên mỗi hosted tool có boundary và pricing riêng.

Agentic Engineer vẫn phải hiểu khi nào nên sử dụng hosted capability, khi nào phải gọi hệ thống doanh nghiệp riêng và dữ liệu nào được phép rời khỏi application boundary.

16. Tool Search và vấn đề Tool Explosion

Khi Agent có 5 tools, model có thể nhìn toàn bộ tool schemas khá dễ dàng.

Khi ecosystem có 300 tools, cách làm đó bắt đầu gặp vấn đề.

Mỗi schema tiêu tốn context.

Tool selection khó hơn.

OpenAI Agents SDK hiện hỗ trợ deferred loading thông qua Tool Search. Agent có thể chỉ load namespace hoặc subset tools khi thực sự cần, thay vì đưa toàn bộ tool inventory vào model từ đầu.

OpenAI khuyến nghị sử dụng namespace cho những nhóm tools liên quan.

Ví dụ:

crm

có thể chứa:

customer profile;
open orders;
interactions.

billing

chứa:

invoice;
payment;
refund.

Điều này gợi mở một vấn đề lớn hơn của Agent architecture:

Khi Agent ecosystem phát triển, tool discovery trở thành infrastructure problem.

Không chỉ Tool Calling.

17. Programmatic Tool Calling

Một capability nâng cao hơn là Programmatic Tool Calling.

Thay vì model phải thực hiện từng tool call trực tiếp qua nhiều model round trips, model có thể sinh JavaScript để điều phối một tập các eligible tools trong một programmatic execution step.

Pattern này phù hợp với những tình huống cần nhiều tool operations có cấu trúc.

Ví dụ cần gọi nhiều data sources hoặc xử lý intermediate results mà không nhất thiết phải quay về full model reasoning sau từng operation.

Đây là một dấu hiệu cho thấy agent runtime đang dần tối ưu hóa không chỉ “model chọn tool nào” mà cả cách tool execution được tổ chức hiệu quả hơn.

18. Agents as Tools

Một Agent cũng có thể được expose như một Tool cho Agent khác.

Ví dụ một Manager Agent có thể gọi:

Finance Specialist;
Research Specialist;
Data Specialist.

Manager vẫn giữ quyền kiểm soát conversation và final answer.

Agents SDK gọi pattern này là Agent.as_tool().

Đây là một phương pháp xây Multi-Agent System mà không cần transfer quyền điều khiển.

Manager gọi specialist giống như gọi một function có intelligence bên trong.

Kết quả quay lại Manager.

Manager có thể tổng hợp nhiều specialist outputs rồi trả lời user.

Pattern này rất phù hợp khi muốn giữ một Agent chịu trách nhiệm cuối cùng.

19. Handoffs

Handoff có semantics khác.

Một Agent chuyển control cho Agent khác.

Trong SDK, handoff được expose với model dưới dạng tool. Ví dụ một handoff sang Refund Agent có thể xuất hiện như một tool kiểu transfer_to_refund_agent.

Ví dụ một Customer Service Triage Agent:

triage_agent = Agent(
    name="Triage",
    instructions="Route customers to the correct specialist.",
    handoffs=[
        billing_agent,
        refund_agent,
        technical_support_agent,
    ],
)

Nếu user có vấn đề refund, Agent có thể hand off conversation cho Refund Agent.

Refund Agent sau đó trở thành Agent đang hoạt động.

Handoffs cũng hỗ trợ input filters để developer kiểm soát phần history hoặc context được chuyển cho Agent mới.

Đây là một capability quan trọng cho isolation và context control.

20. Agents-as-Tools và Handoffs khác nhau ở đâu?

Hai pattern đều liên quan tới nhiều Agents nhưng semantics rất khác.

Pattern	Ai giữ control?	Phù hợp
Agent-as-Tool	Manager Agent	Tổng hợp nhiều specialist results
Handoff	Specialist mới	Chuyển ownership cuộc hội thoại

Nếu một CEO Agent cần lấy phân tích Finance rồi tiếp tục tổng hợp với Sales, Agents-as-Tools thường tự nhiên hơn.

Nếu Customer Service Triage xác định user cần chuyên viên Refund xử lý trực tiếp, Handoff hợp lý hơn.

Agents SDK documentation xem đây là hai core orchestration patterns.

Không nên chọn Multi-Agent architecture chỉ vì “nhiều Agent hiện đại hơn”.

Chọn theo ownership.

21. Agent Orchestration bằng LLM và bằng Code

OpenAI chia orchestration thành hai hướng lớn.

Một là cho LLM quyết định flow.

Hai là code quyết định flow.

LLM-driven orchestration phù hợp với task mở, nơi model cần plan và chọn next step.

Code-driven orchestration phù hợp khi process cần predictable hơn.

Ví dụ classification Agent có thể tạo structured result:

{
  "department": "finance"
}

Sau đó Python code quyết định gọi Finance Agent.

Đây thường là kiến trúc tốt hơn việc để model tự handoff nếu business routing rule rất rõ.

SDK không ép mọi orchestration phải agentic.

Đây là một triết lý thiết kế đáng chú ý.

Agent intelligence và deterministic code có thể kết hợp trong cùng workflow.

22. Structured Outputs

Một Agent không nhất thiết phải trả string.

output_type cho phép định nghĩa structured output.

Ví dụ:

from pydantic import BaseModel

class LeadAssessment(BaseModel):
    score: int
    priority: str
    recommended_action: str

agent = Agent(
    name="Lead Analyst",
    instructions="Assess incoming sales leads.",
    output_type=LeadAssessment
)

SDK sử dụng JSON schema để hướng model tạo output phù hợp và parse kết quả về Python object. Strict JSON schema được khuyến nghị để tăng khả năng output hợp lệ.

Structured Output cực kỳ quan trọng trong production.

Natural language tốt cho con người.

Structured data tốt cho software.

Một architecture mạnh thường để AI giải quyết phần interpretation, sau đó chuyển kết quả về schema trước khi deterministic business logic tiếp tục.

23. Context Management

“Context” là một trong những thuật ngữ dễ gây hiểu nhầm nhất trong Agent development.

Agents SDK phân biệt ít nhất hai loại.

Local context dành cho code.

LLM context dành cho model.

Đây là distinction cực kỳ quan trọng.

Một object chứa database client có thể cần cho tool execution.

Nhưng không có lý do để serialize toàn bộ database client vào prompt.

Một user ID có thể tồn tại trong local context để tool biết đang thao tác cho ai.

Nếu model cần biết user name thì mới đưa thông tin đó vào LLM context.

Không phải dữ liệu application nào cũng nên đi vào model.

24. Local Context và LLM Context khác nhau thế nào?

Local context được truyền qua RunContextWrapper.

Ví dụ:

from dataclasses import dataclass

@dataclass
class AppContext:
    user_id: str
    tenant_id: str

Sau đó:

result = await Runner.run(
    agent,
    input="Check my open orders",
    context=AppContext(
        user_id="u_123",
        tenant_id="company_a"
    )
)

Tool functions và lifecycle hooks có thể truy cập context này.

Điều đặc biệt quan trọng: local context không tự động được gửi cho LLM.

Đây là một security và architecture feature.

Application có thể giữ credentials, service clients hoặc permission state ở local context mà model không cần nhìn thấy.

LLM context nên chỉ chứa thông tin model thực sự cần để reasoning.

25. Sessions và Conversation Memory

Nếu Agent chỉ chạy một turn, state khá đơn giản.

Nếu user quay lại hỏi:

Còn đơn thứ hai thì sao?

Agent cần biết conversation trước.

Agents SDK cung cấp Sessions để tự động duy trì history giữa nhiều Runner runs.

Ví dụ:

from agents import SQLiteSession

session = SQLiteSession("conversation_123")

result = await Runner.run(
    agent,
    "Where is order A100?",
    session=session
)

result = await Runner.run(
    agent,
    "What about A101?",
    session=session
)

SDK tự retrieve previous history và lưu new items.

Session implementations hiện khá đa dạng, từ SQLite, Redis, SQLAlchemy, MongoDB, Dapr tới OpenAI Conversations và wrappers hỗ trợ compaction.

Ngoài ra còn có EncryptedSession, cho phép wrap session store với encryption và TTL.

Đây là một ví dụ rõ ràng cho thấy Agents SDK đang đi xa hơn một demo framework.

26. Sessions khác Business State như thế nào?

Đây là một distinction rất quan trọng.

Session history nói rằng:

User đã nói gì và Agent đã trả lời gì?

Business state nói rằng:

Order hiện đang ở trạng thái nào?

Không nên để conversation memory trở thành source of truth cho business.

Nếu user thanh toán invoice, thông tin đó phải nằm trong payment system hoặc database.

Không nên chỉ nằm trong Agent history.

Session phục vụ context.

Business database phục vụ truth.

Nhầm hai lớp này có thể tạo những hệ thống rất nguy hiểm.

27. Guardrails

Guardrails cho phép application kiểm tra input và output của Agent.

OpenAI hỗ trợ Input Guardrails, Output Guardrails và Tool Guardrails.

Ví dụ một Customer Service Agent dùng model mạnh và tốn chi phí.

Application có thể chạy một guardrail rẻ hơn để xác định request có thuộc phạm vi customer support hay không.

Nếu không, execution có thể bị dừng trước khi Agent chính chạy.

Guardrails có khái niệm tripwire.

Khi guardrail phát hiện violation, run có thể được dừng hoặc raise exception.

Điều đáng chú ý là Input Guardrails có execution modes khác nhau. Blocking guardrail có thể đảm bảo model chính không bắt đầu trước khi validation hoàn tất; parallel guardrail có latency tốt hơn nhưng model chính có thể đã bắt đầu chạy trước khi guardrail trả kết quả.

Đây là một trade-off thật sự giữa latency và cost/risk.

28. Tool Guardrails và Security Boundary

Tool Guardrails đặc biệt quan trọng khi Agent bắt đầu hành động.

Ví dụ Agent muốn gọi:

refund(order_id, amount)

Tool input guardrail có thể kiểm tra:

amount có hợp lệ không;
user có quyền không;
action có cần approval không.

Tool output guardrail có thể kiểm tra dữ liệu trả về trước khi model nhận nó.

Tuy nhiên Guardrails không nên là security layer duy nhất.

Authentication, authorization và business policy vẫn nên được enforce ở tool hoặc backend.

Model behavior là probabilistic.

Permission enforcement nên deterministic.

29. Human-in-the-loop

Agents SDK có flow Human-in-the-loop để pause execution cho tới khi một người approve hoặc reject sensitive tool calls.

Tool có thể khai báo cần approval.

Nếu Agent muốn gọi tool, RunResult xuất hiện interruption.

Application lưu RunState.

Human review.

Sau đó execution được resume.

Điều đáng chú ý là approval có tính run-wide. Nó vẫn hoạt động khi tool nằm trong Agent được handoff hoặc nested Agent-as-Tool execution.

Điều này phù hợp với enterprise workflows như:

gửi email ra ngoài;
refund;
publish content;
thay đổi record quan trọng;
chạy shell command nhạy cảm.

Human-in-the-loop không phải dấu hiệu Agent yếu.

Nó là một design pattern cho risk management.

30. RunState và khả năng Pause/Resume

Khi Agent bị dừng để chờ approval, runtime phải có khả năng lưu chính xác nó đang ở đâu.

RunState được dùng cho mục tiêu này.

Một run có thể được serialize, lưu và sau đó resume khi decision có sẵn.

Đây là một bước rất lớn so với chatbot request-response truyền thống.

Một workflow có thể:

bắt đầu lúc 9 giờ;
chờ Manager approve;
được tiếp tục lúc 14 giờ;
không cần chạy lại từ đầu.

Đây chính là nền tảng cho long-running Agent workflows.

31. Model Context Protocol

MCP chuẩn hóa cách applications expose tools và context cho language models.

Agents SDK hỗ trợ MCP trực tiếp và nhiều transport khác nhau.

Có thể sử dụng:

Hosted MCP;
Streamable HTTP;
HTTP/SSE;
stdio.

Thay vì mỗi Agent integration phải có custom connector, MCP cho phép xây một reusable server cung cấp tools.

Ví dụ CRM MCP Server có thể expose:

get_customer
list_orders
create_note

Nhiều AI applications khác nhau có thể reuse server đó.

Đây là lý do MCP có tiềm năng trở thành một lớp infrastructure quan trọng của Agent ecosystems.

32. Hosted MCP và Local MCP

Hosted MCP cho phép Responses API tương tác với một publicly reachable MCP Server thay mặt model.

Application có thể tạo:

HostedMCPTool(...)

và model có thể discover, gọi remote tools mà không cần Python process tự thực hiện từng round trip.

Local MCP transports lại cho phép application trực tiếp kết nối server qua HTTP, SSE hoặc stdio.

Hai mô hình có trust boundary khác nhau.

Hosted MCP chuyển tool round trip vào OpenAI infrastructure.

Local MCP giữ execution nhiều hơn ở application side.

Không có lựa chọn mặc định tốt nhất.

Phải xem network, credentials, latency và security requirements.

33. Tool Filtering, Approval và MCP Security

Một MCP Server có thể expose hàng chục tools.

Không phải Agent nào cũng nên thấy toàn bộ.

Agents SDK hỗ trợ static và dynamic tool filtering.

Có thể dựa trên context để chỉ expose tools user hiện tại được phép sử dụng.

Ví dụ Finance Agent nhìn thấy:

get_invoice

nhưng không nhất thiết nhìn thấy:

delete_invoice.

MCP tools cũng có approval mechanisms.

OpenAI documentation đặc biệt cảnh báo rằng MCP tools có thể truy cập dữ liệu hoặc hành động với credentials application cung cấp. Vì vậy chỉ nên kết nối trusted servers, sử dụng least-privilege credentials và yêu cầu approval cho sensitive operations.

MCP làm integration dễ hơn.

Nó không làm trust problem biến mất.

34. Sandbox Agents

Đây là một trong những capability mới và quan trọng nhất của Agents SDK.

Sandbox Agents hiện ở trạng thái beta và cung cấp một persistent isolated workspace để Agent có thể search files, chỉnh sửa file, chạy command, tạo artifacts và tiếp tục công việc từ saved sandbox state.

Một Sandbox Agent sử dụng thêm những concept như:

Manifest;
workspace files;
capabilities;
SandboxRunConfig;
sandbox client;
snapshots/session state.

OpenAI đã mở rộng Agents SDK trong tháng 4/2026 với model-native harness và native sandbox execution cho các long-horizon tasks. Mục tiêu là tách harness khỏi compute để cải thiện security, durability và scale.

Đây là kiến trúc phù hợp với coding Agent, document processing Agent hoặc các nhiệm vụ cần thao tác trên một workspace thực sự.

35. Khi nào cần Sandbox thay vì Tool?

Nếu Agent chỉ thỉnh thoảng cần chạy một command, Shell Tool có thể đủ.

Nếu task thực sự xoay quanh một workspace có file, repositories, state và execution environment, Sandbox Agent phù hợp hơn.

Ví dụ:

Đọc repository, sửa bug, chạy test và tạo patch.

Đây không còn là một isolated function call.

Agent cần filesystem context.

Có thể cần nhiều shell operations.

File state phải persist giữa steps.

Sandbox tạo một computational environment rõ ràng cho task.

Đây cũng là một security boundary mạnh hơn so với cho Agent truy cập trực tiếp host machine.

36. Tracing và Observability

Agent behavior khó debug hơn một API call đơn giản.

Một run có thể gồm nhiều model calls, tools và handoffs.

Agents SDK bật tracing mặc định và ghi lại một record toàn diện của workflow, bao gồm LLM generations, tool calls, handoffs, guardrails và custom events.

Tracing gồm:

Trace

đại diện cho một end-to-end workflow.

Và:

Span

đại diện cho một operation bên trong trace.

Một trace có thể chứa generation span, tool span, Agent span và handoff span.

Thông qua Trace viewer, developer có thể xem Agent đã làm gì và tại sao workflow mất thời gian hoặc thất bại.

Một caveat quan trọng: tài liệu hiện tại cho biết built-in tracing không khả dụng với những organization sử dụng API theo Zero Data Retention policy.

Production observability cần xem xét cả privacy policy lẫn debugging requirements.

37. Usage Tracking và Cost Control

Agents SDK tự động theo dõi usage của mỗi run.

Các metric gồm:

số model requests;
input tokens;
output tokens;
total tokens;
cached tokens;
reasoning tokens;
per-request usage breakdown.

Có thể truy cập:

result.context_wrapper.usage

Usage tracking đặc biệt quan trọng với Agent.

Một chatbot thường gọi model một lần.

Một Agent có thể gọi model 10 lần.

Multi-Agent có thể gọi nhiều hơn nữa.

Không đo usage thì rất khó biết economics của system.

Một production dashboard nên theo dõi ít nhất:

task success + latency + model requests + tokens + cost

Chất lượng mà không có economics chưa đủ để đánh giá một Agent production.

38. Testing Agent Workflows

Một trong những bổ sung rất có giá trị của Agents SDK hiện tại là deterministic testing utilities.

SDK cung cấp ScriptedModel, scripted Sandbox sessions, Realtime test doubles và Voice testing components. Chúng chạy in-memory, không cần gọi model provider thật và cho phép kiểm tra orchestration do SDK/application sở hữu.

Ví dụ:

from agents.testing import ScriptedModel, assistant_message

model = ScriptedModel([

[assistant_message("Paris is the capital of France.")]

])

Sau đó test có thể assert final output và số model calls.

ScriptedModel còn hỗ trợ mô phỏng:

tool calls;
model failures;
streaming;
retries;
unexpected extra model turns.

Điểm cực kỳ quan trọng là phân biệt workflow testing với model evaluation.

ScriptedModel kiểm tra:

Runtime của application có hoạt động đúng không?

Nó không kiểm tra:

Model production có reasoning tốt không?

Hai lớp test này phải tồn tại song song.

39. Agent Visualization

SDK có optional visualization support dùng Graphviz.

draw_graph() tạo representation của Agents, Tools, MCP Servers và Handoffs.

Capability này có vẻ nhỏ nhưng rất hữu ích khi hệ thống bắt đầu có nhiều Agents.

Một graph có thể giúp team nhanh chóng thấy:

Agent nào có tool gì;
Agent nào có thể handoff đi đâu;
MCP Servers nào được kết nối.

Trong các hệ thống enterprise lớn, architecture visualization không chỉ phục vụ developer.

Nó có thể hỗ trợ design review và security review.

40. Realtime Agents

Agents SDK không chỉ dành cho text.

Realtime Agents dùng OpenAI Realtime API qua WebSocket để tạo low-latency agents có khả năng xử lý text và audio liên tục, gọi tools và xử lý interruption trong một live session.

Các component chính gồm:

RealtimeAgent;
RealtimeRunner;
RealtimeSession;
RealtimeModel.

Khác text Agent thông thường, runner.run() của realtime layer trả một live session chứ không phải final result ngay lập tức.

Session giữ connection mở.

User gửi audio hoặc text.

Model phát events liên tục.

Tools có thể chạy trong conversation.

Agent có thể handoff.

Realtime tools cũng có approval flow.

Điều này rất phù hợp cho voice customer service hoặc conversational applications có độ trễ thấp.

41. Voice Pipelines

Voice Pipeline là một kiến trúc khác Realtime Agent.

Pipeline gồm ba bước:

speech-to-text, Agent workflow và text-to-speech.

Mô hình này hữu ích khi muốn reuse một text Agent workflow hiện có nhưng thêm voice interface.

Realtime Agent thì model interaction bản thân mang tính realtime và connection dài.

Voice Pipeline lại giống một pipeline processing rõ ràng hơn.

Hai kiến trúc giải những latency và interaction requirements khác nhau.

Đây là một ví dụ nữa cho thấy Agents SDK không ép tất cả AI interactions vào một runtime duy nhất.

42. Durable Execution

Human approval tạo ra một bài toán:

Agent có thể phải chờ nhiều giờ.

Long-horizon Agent tạo bài toán lớn hơn:

Workflow có thể chạy rất lâu hoặc process có thể restart.

Agents SDK hiện có integration với các durable orchestration systems như Dapr, Temporal, Restate và DBOS.

Các integration này cho phép Agent workflow phục hồi sau failures hoặc process restarts và duy trì progress.

Đây là nơi Agentic Engineering bắt đầu gặp Distributed Systems Engineering.

Các khái niệm như:

checkpoint;
retry;
idempotency;
resume;
durable state;

trở nên cực kỳ quan trọng.

Agent không thể chỉ “thông minh”.

Nó phải sống sót qua failure.

43. OpenAI Agents SDK và Multi-Agent Systems

Agents SDK cho phép xây Multi-Agent theo nhiều cách, nhưng điều đáng chú ý là SDK không tạo một abstraction Multi-Agent quá phức tạp.

Các building blocks chủ yếu vẫn là:

Agent;
Agent-as-Tool;
Handoff;
Python code orchestration.

Đây là một design philosophy khá rõ.

Multi-Agent không được xem là một loại hệ thống hoàn toàn khác.

Nó là sự composition của Agents.

Một Manager có thể gọi Specialists.

Một Triage Agent có thể handoff.

Code có thể chạy Agents song song bằng asyncio.

Code có thể chain Agents tuần tự.

Sự đơn giản này có lợi cho production vì flow vẫn tương đối dễ hiểu.

44. Một kiến trúc Production tham khảo

Một Agent application production có thể được chia thành các lớp.

Lớp API xử lý authentication và request lifecycle.

Agent Runtime dùng Runner.

Application Context giữ identity, tenant, data clients và permission state.

Tools expose business capabilities.

Sessions giữ conversational history.

Database giữ business state.

Guardrails kiểm tra model boundaries.

Human Approval kiểm soát sensitive actions.

Tracing và Usage cung cấp observability.

Evals và tests kiểm soát quality trước release.

Nếu workflow dài, durable orchestrator lưu execution state.

Nếu Agent cần filesystem, Sandbox tạo execution boundary.

Nếu organization có nhiều tools, MCP có thể trở thành integration layer.

Điều quan trọng nhất của kiến trúc này là:

Không đặt mọi trách nhiệm vào Agent.

Agent xử lý reasoning.

Software xử lý invariants.

Database giữ truth.

IAM giữ permissions.

Observability ghi lại execution.

Human xử lý những quyết định cần accountability cao.

45. Case Study: Enterprise Customer Service Agent

Giả sử một doanh nghiệp muốn xây Customer Service Agent.

User hỏi:

Tôi đã trả tiền nhưng đơn hàng vẫn chưa được giao. Kiểm tra giúp tôi.

Agent có ba tools:

get_customer
get_order
get_payment

Agent xác định customer từ authenticated application context.

Nó không yêu cầu model tự đoán customer ID.

Sau đó gọi get_order.

Order trả trạng thái payment_pending.

Agent thấy user nói đã thanh toán nên gọi get_payment.

Payment system trả paid.

Có mismatch giữa Payment và Order.

Agent có thể gọi thêm:

create_support_ticket

Nhưng đây là write operation.

Nếu ticket creation có risk thấp, application có thể cho phép tự động.

Nếu Agent muốn refund, tool khác yêu cầu human approval.

Session giữ conversation history.

Business systems vẫn giữ order và payment truth.

Trace ghi lại toàn bộ tool trajectory.

Usage đo chi phí.

Eval dataset kiểm tra những case như:

payment success nhưng order stale;
payment failed;
duplicate payment;
order cancelled;
customer không có quyền xem order.

Đây chính là một production Agent.

Không phải chỉ chatbot được nối thêm function calling.

46. Những lỗi phổ biến khi sử dụng Agents SDK

Lỗi đầu tiên là nghĩ rằng Agent càng nhiều tools càng mạnh.

Tool surface quá lớn có thể làm model khó lựa chọn, tăng context và tăng security surface. Tool Search, namespaces và MCP filtering tồn tại một phần để xử lý vấn đề này.

Lỗi thứ hai là để instructions đóng vai trò authorization.

Không nên.

Tool/backend phải enforce permission.

Lỗi thứ ba là sử dụng session history làm business state.

Session là memory layer, không phải transactional database.

Lỗi thứ tư là tạo quá nhiều Agents.

Một Agent có tools tốt thường đơn giản hơn năm Agents liên tục handoff.

Lỗi thứ năm là chỉ xem final_output.

Tool items, interruptions, traces và usage thường quan trọng không kém.

Lỗi thứ sáu là không giới hạn turns.

Agent loop cần control.

Lỗi thứ bảy là không đo token usage.

Agent economics rất khác single-call applications.

Lỗi thứ tám là test bằng cách chat tay.

SDK hiện đã có deterministic testing utilities. Không có lý do để bỏ qua software tests.

Lỗi thứ chín là bật sensitive tool action mà không có approval.

Lỗi cuối cùng là dùng Sandbox khi một function tool đơn giản đã đủ, hoặc ngược lại cố nhồi một workspace-heavy task vào hàng chục function calls.

Chọn abstraction phải theo workload.

47. Khi nào không nên dùng Agents SDK?

Agents SDK rất hữu ích, nhưng không phải mọi AI application đều cần nó.

Nếu application chỉ cần:

Input vào, model trả structured result.

Responses API trực tiếp có thể đơn giản hơn.

Nếu application muốn tự viết agent loop hoàn toàn custom, Responses API cũng cho nhiều control hơn.

Nếu workflow hoàn toàn deterministic, thậm chí có thể không cần Agent.

Ví dụ:

upload CSV → validate → transform → save

đây chủ yếu là data processing pipeline.

Thêm Agent chỉ vì muốn “AI-native” có thể làm system khó predict hơn mà không tạo thêm giá trị.

OpenAI chính thức cũng phân biệt rõ trường hợp nên dùng Responses API trực tiếp và khi nên dùng Agents SDK.

Một kỹ sư giỏi không phải người dùng Agents SDK cho mọi thứ.

Mà là người hiểu lúc nào runtime này thực sự giải quyết complexity.

48. Roadmap học OpenAI Agents SDK

Không nên học tài liệu theo đúng thứ tự menu.

Có một thứ tự thực tế hơn.

Giai đoạn 1: Agent và Runner

Trước hết chỉ cần hiểu:

Agent
Runner
RunResult

Xây Agent đơn giản không tool.

Hiểu một run là gì.

Hiểu Agent loop.

Giai đoạn 2: Function Tools

Thêm hai hoặc ba tools.

Quan sát model chọn tool.

Đọc new_items.

Bật tracing.

Không vội Multi-Agent.

Giai đoạn 3: Structured Output và Context

Học output_type.

Tách Local Context khỏi LLM Context.

Đưa identity và dependencies vào context đúng cách.

Giai đoạn 4: Sessions

Xây multi-turn Agent.

So sánh to_input_list(), Session và server-managed continuation.

Hiểu không được tùy tiện trộn các persistence strategies trong cùng một run.

Giai đoạn 5: Guardrails và Human Approval

Thêm write tool.

Yêu cầu approval.

Pause.

Serialize state.

Resume.

Đây là bước quan trọng để hiểu Agent workflow khác chatbot.

Giai đoạn 6: Handoffs và Agents-as-Tools

Chỉ bây giờ mới thêm Agent thứ hai.

Thử cả manager pattern và handoff pattern.

Quan sát khác biệt về ownership.

Giai đoạn 7: MCP

Xây một MCP integration thật.

Học filtering, approval và caching.

Không chỉ kết nối public demo server.

Giai đoạn 8: Testing và Tracing

Viết deterministic tests với ScriptedModel.

Tạo trace workflow names.

Theo dõi usage.

Bắt đầu đo Agent như một software system.

Giai đoạn 9: Sandbox và Durable Execution

Nếu use case cần file workspace hoặc long-running tasks, học Sandbox Agents và durable orchestrators.

Không học hai phần này nếu workload không cần.

Giai đoạn 10: Realtime hoặc Voice

Chỉ học nếu product cần conversational voice.

Không nên xem Voice là requirement mặc định của Agent Engineering.

49. Agents SDK tiết lộ điều gì về tương lai Agent Engineering?

Một điều thú vị khi đọc tài liệu Agents SDK không nằm ở từng API.

Nó nằm ở những abstraction OpenAI quyết định đưa vào SDK.

Ban đầu có Agent, Tool, Handoff và Guardrail.

Sau đó Sessions trở nên quan trọng.

Human Approval xuất hiện.

Tracing trở thành built-in.

MCP trở thành first-class integration.

Sandbox xuất hiện cho long-running workspace tasks.

Testing utilities được bổ sung.

Usage accounting trở thành explicit.

Durable execution được kết nối với workflow engines.

Realtime và Voice có runtimes riêng.

Nhìn toàn bộ hệ thống, có thể thấy Agent Engineering đang dần giống một lĩnh vực Software Engineering hoàn chỉnh.

Vấn đề không còn là:

Prompt thế nào để AI làm đúng?

Mà là:

Runtime nào quản Agent?

State nằm ở đâu?

Tools được expose thế nào?

Agent có identity gì?

Ai được approve action?

Nếu process chết thì workflow resume ở đâu?

Nếu Agent sai thì trace thế nào?

Release mới có regression không?

Cost mỗi task bao nhiêu?

Đây đều là những câu hỏi production engineering.

OpenAI tháng 4/2026 gọi bước tiến mới của Agents SDK là việc cung cấp một model-native harness và native sandbox execution cho các nhiệm vụ trên files và computers, đồng thời tách harness khỏi compute để phục vụ security, durability và scale.

Đó là một tín hiệu rất rõ.

Agent đang chuyển từ prompt pattern thành runtime architecture.

50. Kết luận

OpenAI Agents SDK nhìn bề ngoài là một framework khá nhỏ.

Một Agent.

Một Runner.

Một vài Tools.

Một vài Handoffs.

Nhưng sự đơn giản ở bề mặt che đi một hệ thống runtime ngày càng sâu.

Agent định nghĩa model, instructions, tools và behavior.

Runner quản Agent loop.

Tools mở Agent ra thế giới bên ngoài.

Structured Outputs nối probabilistic reasoning với deterministic software.

Local Context giữ dependencies mà model không cần thấy.

Sessions giữ working conversation memory.

Handoffs và Agents-as-Tools cho phép composition.

Guardrails cung cấp validation.

Human-in-the-loop đưa con người trở thành một phần chính thức của runtime.

RunState cho phép pause và resume.

MCP mở rộng tool ecosystem.

Sandbox tạo isolated execution environment.

Tracing cho phép quan sát Agent trajectory.

Usage giúp kiểm soát economics.

Testing đưa Agent workflow trở lại kỷ luật Software Engineering.

Durable Execution giải bài toán workflow dài và failure recovery.

Realtime và Voice mở Agent ra những interaction model mới.

Khi nhìn toàn bộ hệ thống như vậy, một điều trở nên rõ ràng:

Agents SDK không phải thư viện để tạo chatbot thông minh hơn.

Nó là một attempt nhằm chuẩn hóa những thành phần cơ bản cần có để xây software trong đó LLM có thể reasoning và hành động.

Điều này cũng thay đổi cách nên học SDK.

Không nên chỉ học:

Agent(...)

rồi:

Runner.run(...)

và kết luận đã biết Agents SDK.

Phần có giá trị nhất bắt đầu khi Agent có tools.

Sau đó là state.

Permissions.

Approvals.

Tracing.

Evaluation.

Failure recovery.

Đó chính là đường ranh giữa prototype và production.

Một Agent demo có thể được xây trong vài chục dòng code.

Một Agent production phải trả lời những câu hỏi khó hơn rất nhiều: dữ liệu đến từ đâu, model được phép làm gì, tool nào đáng tin, state lưu ở đâu, action nào cần người duyệt, lỗi được phục hồi thế nào và team có chứng minh được version mới tốt hơn version trước hay không.

OpenAI Agents SDK không tự giải quyết toàn bộ những câu hỏi đó.

Nhưng nó đã đưa phần lớn chúng thành những primitive rõ ràng trong cùng một runtime.

Đó chính là giá trị lớn nhất của SDK.

Và cũng là lý do Agents SDK nên được học không chỉ như một OpenAI library, mà như một tài liệu thực hành về cách Agentic Software đang được kiến trúc hóa.

51. Tài liệu tham khảo

1. OpenAI Agents SDK, Overview. Tài liệu tổng quan về triết lý thiết kế, Agents, Tools, Handoffs, Guardrails, Sessions, Sandbox, Realtime và Tracing.

2. OpenAI Agents SDK, Quickstart. Hướng dẫn cài đặt, tạo Agent đầu tiên, Tools, Handoffs và Runner.

3. OpenAI Agents SDK, Agents. Reference chính về cấu hình Agent, instructions, model, tools, handoffs, guardrails, output types và lifecycle hooks.

4. OpenAI Agents SDK, Running Agents. Tài liệu về Runner, Agent Loop, RunConfig, max turns, state, streaming và durable integrations.

5. OpenAI Agents SDK, Results. Tài liệu về RunResult, final output, run items, last agent, interruptions và resumable state.

6. OpenAI Agents SDK, Streaming. Tài liệu về streaming events, raw Responses events và run item events.

7. OpenAI Agents SDK, Tools. Tổng quan về hosted tools, local execution tools, Function Tools, Agents-as-Tools, Tool Search và Programmatic Tool Calling.

8. OpenAI Agents SDK, Models. Tài liệu về Responses models, Chat Completions, model providers, model mixing, retries và model configuration.

9. OpenAI Agents SDK, Agent Orchestration. Tài liệu về orchestration bằng LLM, code, Agents-as-Tools, Handoffs, chaining và parallel execution.

10. OpenAI Agents SDK, Handoffs. Tài liệu về delegation, handoff configuration, input types và input filters.

11. OpenAI Agents SDK, Agent Output. Reference về structured outputs, JSON schema và output validation.

12. OpenAI Agents SDK, Context Management. Phân biệt local application context và context được cung cấp cho LLM.

13. OpenAI Agents SDK, Sessions. Tài liệu về persistent conversation memory, backends, history management và session strategies.

14. OpenAI Agents SDK, Encrypted Sessions. Tài liệu về transparent session encryption, per-session keys và TTL.

15. OpenAI Agents SDK, Guardrails. Tài liệu về Input, Output, Tool Guardrails, execution modes và tripwires.

16. OpenAI Agents SDK, Human-in-the-loop. Tài liệu về approvals, interruptions, RunState và resume execution.

17. OpenAI Agents SDK, Model Context Protocol. Tài liệu về Hosted MCP, Streamable HTTP, SSE, stdio, filtering, approvals, caching và tracing.

18. OpenAI Agents SDK, Sandbox Agents Quickstart. Tài liệu về persistent workspace, manifests, capabilities, sandbox clients và resumable sandbox state.

19. OpenAI Agents SDK, Sandbox Clients. Hướng dẫn lựa chọn local, Docker và hosted sandbox environments.

20. OpenAI, The Next Evolution of the Agents SDK, April 2026. Giới thiệu model-native harness, native sandbox execution và kiến trúc tách harness khỏi compute.

21. OpenAI Agents SDK, Tracing. Tài liệu về traces, spans, model generations, tools, handoffs, guardrails và production observability.

22. OpenAI Agents SDK, Usage. Tài liệu về request counts, token accounting, reasoning tokens, cache tokens và per-request usage.

23. OpenAI Agents SDK, Testing. Tài liệu về ScriptedModel và deterministic testing cho Agent, Sandbox, Realtime và Voice workflows.

24. OpenAI Agents SDK, Agent Visualization. Tài liệu về Graphviz representation của Agents, Tools, MCP Servers và Handoffs.

25. OpenAI Agents SDK, Realtime Agents Quickstart. Hướng dẫn xây server-side low-latency Agents dựa trên Realtime API và WebSocket.

26. OpenAI Agents SDK, Realtime Agents Guide. Tài liệu sâu hơn về RealtimeAgent, RealtimeRunner, RealtimeSession, tools, approvals và session lifecycle.

27. OpenAI Agents SDK, Realtime Transport. Tài liệu về server-side WebSocket và SIP deployment models.

28. OpenAI Agents SDK, Voice Agents Quickstart. Tài liệu về speech-to-text, Agent workflow và text-to-speech pipeline.

29. OpenAI Agents SDK, Voice Pipeline. Tài liệu về audio input, streamed input, lifecycle events và voice pipeline configuration.

30. OpenAI Agents SDK, Configuration. Tài liệu về API clients, provider defaults, tracing, logging và SDK-level configuration.

31. OpenAI Agents SDK, Release Process and Changelog. Tài liệu theo dõi thay đổi phiên bản, model defaults, MCP dependencies và testing capabilities của SDK.

TechData.AI - Leading the Future.

Tham khảo các khoá học theo link: https://techdata.ai/techdata-ai-course/

Hoàng Minh.