Hướng dẫn OpenAI Agents SDK: Xây dựng hệ thống AI có hành động

Điều kiện tiên quyết khi làm việc với OpenAI Agents SDK

Trước khi đi sâu vào OpenAI Agents SDK, điều quan trọng là hiểu một số khái niệm nền tảng và thiết lập đúng môi trường của bạn. Phần này bao quát mọi thứ bạn cần biết trước khi viết agent đầu tiên.

Kiến thức yêu cầu

Để tận dụng tối đa hướng dẫn này, bạn nên thoải mái với:

• Lập trình Python mức trung cấp: Bạn nên hiểu hàm, lớp, mẫu async/await, và type hint
• Cách sử dụng cơ bản OpenAI API: Quen thuộc với việc gửi yêu cầu tới các mô hình OpenAI và xử lý phản hồi
• Mô hình ngôn ngữ lớn (LLM): Hiểu cách LLM hoạt động về mặt khái niệm và khả năng/giới hạn của chúng
• Pydantic: Kiến thức cơ bản về dùng Pydantic cho kiểm tra dữ liệu sẽ hữu ích, vì Agents SDK sử dụng nhiều
• Lập trình bất đồng bộ: Quen thuộc với mẫu async/await trong Python, vì Agents SDK được xây dựng xoay quanh thực thi bất đồng bộ

Nếu bạn cần củng cố kiến thức ở một số mảng trên, DataCamp cung cấp nhiều tài nguyên xuất sắc:

• Làm việc với OpenAI API — Học các nền tảng tương tác với các mô hình của OpenAI.
• Lộ trình OpenAI Fundamentals — Lộ trình học toàn diện cho công nghệ OpenAI.
• Tổng quan GPT-4.5 — Tìm hiểu về các khả năng mới nhất của các mô hình GPT.
• Gọi hàm với GPT-4.5 — Nền tảng thiết yếu để hiểu cách dùng công cụ trong agent.
• Sử dụng GPT-4.5 API — Hướng dẫn thực hành làm việc với mô hình nâng cao.

Các khái niệm then chốt cho agent

Trước khi bắt đầu viết mã, hãy làm rõ vài khái niệm cốt lõi trung tâm của Agents SDK:

1. Agent: Hệ thống AI có thể dùng công cụ và đưa ra quyết định để hoàn thành nhiệm vụ
2. Công cụ (Tools): Các hàm mà agent có thể gọi để thực hiện hành động như tìm kiếm web hoặc truy cập cơ sở dữ liệu
3. Handoff: Cơ chế chuyển giao quyền kiểm soát giữa các agent chuyên biệt
4. Guardrail: Biện pháp an toàn để kiểm tra đầu vào và đầu ra nhằm đảm bảo hành vi phù hợp

Hiểu các khái niệm này và mối quan hệ của chúng sẽ giúp bạn xây dựng ứng dụng dựa trên agent hiệu quả hơn. Bạn có thể tìm hiểu thêm trong hướng dẫn tìm hiểu về AI agent. 

Thiết lập môi trường OpenAI Agents

Hãy thiết lập môi trường phát triển với mọi thứ cần thiết để làm việc với OpenAI Agents SDK:

Cài đặt các gói cần thiết

Trước tiên, tạo và kích hoạt môi trường ảo:

# Create and activate a virtual environment (run in your terminal)
python -m venv agents-env
source agents-env/bin/activate  # On Windows: agents-env\Scripts\activate

Tiếp theo, cài đặt OpenAI Agents SDK và python-dotenv:

pip install openai-agents python-dotenv

Dùng python-dotenv để quản lý khóa API

Khi làm việc với khóa API, thực hành tốt nhất là không đưa chúng vào mã nguồn. Gói python-dotenv cung cấp cách an toàn để quản lý biến môi trường:

1. Tạo tệp tên .env trong thư mục dự án
2. Thêm khóa OpenAI API của bạn vào tệp này:

OPENAI_API_KEY=your-api-key-here

3. Tải và sử dụng biến môi trường trong mã của bạn:

import os
from dotenv import load_dotenv
from agents import Agent, Runner

# Load environment variables from .env file
load_dotenv()

# Access your API key
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
   raise ValueError("OPENAI_API_KEY not found in .env file")

Cách tiếp cận này giữ thông tin nhạy cảm ngoài mã nguồn, đặc biệt quan trọng nếu bạn chia sẻ hoặc xuất bản công việc của mình.

Làm việc với hàm async

OpenAI Agents SDK sử dụng lập trình bất đồng bộ rộng rãi. Đây là cách làm việc với hàm async trong các môi trường khác nhau:

Trong script Python (tệp .py)

Trong script Python thông thường, bạn cần dùng asyncio.run() để thực thi hàm async:

import asyncio
from agents import Agent, Runner

async def main():
   agent = Agent(
       name="Test Agent",
       instructions="You are a helpful assistant that provides concise responses."
   )
   result = await Runner.run(agent, "Hello! Are you working correctly?")
   print(result.final_output)

if __name__ == "__main__":
   asyncio.run(main())  # Run the async function

Trong Jupyter notebook

Jupyter notebook đã có một vòng lặp sự kiện chạy sẵn, nên bạn KHÔNG nên dùng asyncio.run(). Thay vào đó, bạn có thể await trực tiếp các hàm async:

from agents import Agent, Runner

# No need for asyncio.run() in notebooks
agent = Agent(
   name="Test Agent",
   instructions="You are a helpful assistant that provides concise responses."
)
result = await Runner.run(agent, "Hello! Are you working correctly?")
print(result.final_output)

Nếu bạn cố dùng asyncio.run() trong notebook, bạn sẽ gặp lỗi như sau:

RuntimeError: asyncio.run() cannot be called from a running event loop

Đây là một trong những điều chỉnh phổ biến nhất bạn cần thực hiện khi sao chép mã giữa script và notebook. Xuyên suốt hướng dẫn này, tôi chủ yếu dùng cú pháp thân thiện với notebook vì đa số độc giả sẽ sử dụng Jupyter.

Kiểm tra cài đặt

Hãy đảm bảo mọi thứ đã được thiết lập đúng:

from agents import Agent, Runner
from dotenv import load_dotenv

load_dotenv()

# For Jupyter notebooks:
agent = Agent(
   name="Test Agent",
   instructions="You are a helpful assistant that provides concise responses."
)
result = await Runner.run(agent, "Hello! Are you working correctly?")
print(result.final_output)

# For Python scripts, you'd use:
# async def test_installation():
#     agent = Agent(
#         name="Test Agent",
#         instructions="You are a helpful assistant that provides concise responses."
#     )
#     result = await Runner.run(agent, "Hello! Are you working correctly?")
#     print(result.final_output)
#
# if __name__ == "__main__":
#     asyncio.run(test_installation())

# Hello! Yes, I'm here and ready to help. How can I assist you today?

Với thiết lập này, bạn đã sẵn sàng bắt đầu xây dựng ứng dụng với OpenAI Agents SDK.

Bắt đầu với OpenAI Agents SDK

Trung tâm của OpenAI Agents SDK là lớp Agent, phục vụ như giao diện chính để tạo hệ thống AI có thể hiểu và thực hiện theo chỉ dẫn. Hãy khám phá cách tạo và cấu hình agent cho các kịch bản khác nhau.

Một agent trong SDK này đại diện cho hệ thống AI có khả năng làm theo hướng dẫn và, tùy chọn, sử dụng công cụ để hoàn thành nhiệm vụ. Tạo một agent cơ bản chỉ cần vài tham số thiết yếu:

from agents import Agent

basic_agent = Agent(
   name="My First Agent",
   instructions="You are a helpful assistant that provides factual information.",
   model="gpt-4o"  # Optional: defaults to "gpt-4o" if not specified
)

Ba thành phần chính của một agent là:

1. Tên: Định danh cho agent giúp ghi nhật ký và gỡ lỗi
2. Hướng dẫn: “Lời nhắc hệ thống” cốt lõi xác định hành vi và mục đích của agent
3. Mô hình: Mô hình ngôn ngữ nền tảng vận hành agent (mặc định là GPT-4o)

Trong khi thiết lập cơ bản là đủ để bắt đầu, lớp Agent còn cung cấp một số tùy chọn cấu hình mô hình bổ sung cho phép bạn kiểm soát tốt hơn hành vi của LLM:

from agents import ModelSettings


advanced_agent = Agent(
   name="Advanced Assistant",
   instructions="""You are a professional, concise assistant who always provides
   accurate information. When you don't know something, clearly state that.
   Focus on giving actionable insights when answering questions.""",
   model="gpt-4o",
   model_settings=ModelSettings(
       temperature=0.3,  # Lower for more deterministic outputs (0.0-2.0)
       max_tokens=1024,  # Maximum length of response
   ),
   tools=[]  # We'll cover tools in a later section
)

Hướng dẫn và cấu hình

Tham số instructions có lẽ là khía cạnh quan trọng nhất của thiết kế agent. Nó hoạt động như một “lời nhắc hệ thống” định hướng hành vi, giọng điệu và khả năng của agent. Viết hướng dẫn hiệu quả vừa là nghệ thuật vừa là khoa học:

Thực tiễn tốt khi viết hướng dẫn

1. Cụ thể: Xác định rõ vai trò, cá tính và giới hạn của agent
2. Đặt ranh giới: Nêu rõ chủ đề hoặc hành động agent nên tránh
3. Xác định mẫu tương tác: Giải thích cách agent xử lý các loại đầu vào khác nhau
4. Thiết lập ranh giới kiến thức: Làm rõ agent nên biết gì và khi nào cần thừa nhận không chắc chắn

Agent cũng bao gồm tham số description, là mô tả dễ đọc dành cho con người về agent, được sử dụng khi agent nằm trong công cụ/handoff.

Tùy chọn cấu hình

Ngoài hướng dẫn, bạn có thể tinh chỉnh hành vi agent bằng một số tham số cấu hình:

• temperature: Kiểm soát mức ngẫu nhiên trong phản hồi (0.0–2.0)
• Giá trị thấp (0.1–0.4) cho phản hồi quyết đoán, tập trung hơn
• Giá trị cao (0.7–1.0) tạo đầu ra sáng tạo, đa dạng hơn
• max_tokens: Giới hạn độ dài phản hồi của agent
• Hữu ích để đảm bảo đầu ra súc tích hoặc kiểm soát chi phí
• Mặc định thay đổi theo mô hình nhưng thường đủ cao cho đa số trường hợp
• model: Chọn LLM nền tảng
• “gpt-4o” cho hiệu năng tốt nhất với phần lớn trường hợp
• “gpt-4o-mini” cân bằng tốt giữa hiệu năng và chi phí
• “gpt-3.5-turbo” phù hợp tác vụ ít phức tạp ưu tiên tốc độ và chi phí

Các tùy chọn cấu hình này cung cấp khung mạnh mẽ để tùy biến hành vi agent phù hợp nhiều ứng dụng. Chúng tôi khuyến khích bạn thử các thiết lập khác nhau để khám phá tác động tới phản hồi của agent và tìm cấu hình tối ưu cho trường hợp của bạn.

Ví dụ OpenAI Agents SDK: Xây dựng trợ lý thời tiết chuyên biệt

Giờ hãy tổng hợp các khái niệm này bằng một ví dụ thực tiễn: trợ lý thông tin thời tiết chuyên biệt. Ví dụ này minh họa cách tạo một agent với chuyên môn, khả năng và giới hạn được xác định rõ ràng:

from agents import Agent, Runner
from dotenv import load_dotenv

# Load environment variables (API key)
load_dotenv()

# Define detailed instructions for our weather assistant
weather_instructions = """
You are a weather information assistant who helps users understand weather patterns and phenomena.

YOUR EXPERTISE:
- Explaining weather concepts and terminology
- Describing how different weather systems work
- Answering questions about climate and seasonal patterns
- Explaining the science behind weather events

LIMITATIONS:
- You cannot provide real-time weather forecasts for specific locations
- You don't have access to current weather data
- You should not make predictions about future weather events

STYLE:
- Use clear, accessible language that non-meteorologists can understand
- Include interesting weather facts when relevant
- Be enthusiastic about meteorology and climate science
"""

# Create our specialized weather assistant
weather_assistant = Agent(
   name="WeatherWise",
   instructions=weather_instructions,
   model="gpt-3.5-turbo",
   model_settings=ModelSettings(
       temperature=0.5,  # Balanced temperature for natural but focused responses
       max_tokens=256,  # Maximum length of response
   )
)

Chạy agent đầu tiên của bạn

Sau khi tạo agent, bạn có thể chạy nó bằng lớp Runner. Lớp này xử lý việc thực thi tác vụ của agent và quản lý luồng hội thoại:

# For Jupyter notebooks:
result = await Runner.run(
   weather_assistant, "Can you tell me about the relationship between climate change and extreme weather events?"
)

print(result.final_output)

—--------

Absolutely! Climate change is closely linked to the increase in frequency and intensity of extreme weather events. As the Earth's climate warms due to the buildup of greenhouse gases in the atmosphere, it disrupts the balance of our planet's climate systems.

Here's how climate change influences extreme weather events:
1. **Heatwaves**: Rising global temperatures lead to more frequent and severe heatwaves. These events can have serious impacts on human health, agriculture, and ecosystems.

2. **Intense Storms**: Warmer oceans provide more energy to fuel hurricanes, typhoons, and other tropical storms, leading to stronger and more destructive events.

3. **Heavy Rainfall**: A warmer atmosphere can hold more moisture, resulting in heavier rainfall during storms. This can lead to flooding and landslides.

4. **Droughts**: Climate change can exacerbate drought conditions in certain regions, impacting water resources, agriculture, and ecosystems.

5. **Wildfires**: Higher temperatures and drier conditions increase the likelihood of wildfires, which can be more frequent and intense.

It's important to note that while climate change doesn't directly cause specific weather events, it can increase the likelihood and severity of extreme weather occurrences. Scientists continue to study these connections to better understand and prepare for the impacts of

Với script Python, bạn sẽ cần dùng phương pháp asyncio:

# For Python scripts:
import asyncio

async def run_agent_example():
   result = await Runner.run(weather_assistant, "Can you tell me about the relationship between climate change and extreme weather events?")
   print(result.final_output)

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

Trong phần này, chúng ta đã bao quát nền tảng tạo và chạy agent với OpenAI Agents SDK. Ở phần tiếp theo, chúng ta sẽ mở rộng các khái niệm này bằng cách thêm công cụ cho agent, điều sẽ tăng cường đáng kể khả năng của chúng.

Làm việc với Công cụ

Sức mạnh thực sự của OpenAI Agents SDK xuất hiện khi bạn trang bị công cụ cho agent. Công cụ cho phép agent tương tác với hệ thống bên ngoài, truy cập dữ liệu và thực hiện hành động vượt ra ngoài việc chỉ tạo văn bản. Agents SDK hỗ trợ ba loại công cụ chính: công cụ được lưu trữ (hosted), công cụ hàm (function tools) và agent như công cụ.

Công cụ hosted

Công cụ hosted chạy trên máy chủ của OpenAI cùng với các mô hình ngôn ngữ. Những công cụ này cung cấp năng lực tích hợp sẵn mà không yêu cầu bạn triển khai chức năng phức tạp.

WebSearchTool: Xây dựng trợ lý nghiên cứu

WebSearchTool cung cấp cho agent khả năng tìm kiếm web để lấy thông tin cập nhật. Điều này đặc biệt giá trị cho các tác vụ cần kiến thức hiện tại vượt ngoài dữ liệu huấn luyện của mô hình.

from agents import Agent, Runner, WebSearchTool
from dotenv import load_dotenv

load_dotenv()

# Create a research assistant with web search capability
research_assistant = Agent(
   name="Research Assistant",
   instructions="""You are a research assistant that helps users find and summarize information.
   When asked about a topic:
   1. Search the web for relevant, up-to-date information
   2. Synthesize the information into a clear, concise summary
   3. Structure your response with headings and bullet points when appropriate
   4. Always cite your sources at the end of your response
  
   If the information might be time-sensitive or rapidly changing, mention when the search was performed.
   """,
   tools=[WebSearchTool()]
)

async def research_topic(topic):
   result = await Runner.run(research_assistant, f"Please research and summarize: {topic}. Only return the found links with very minimal text.")
   return result.final_output

# Usage example (in Jupyter notebook)
summary = await research_topic("Latest developments in personal productivity apps.")
print(summary[:512])

—----------------

Here are some recent developments in personal productivity apps:

- **AI Integration in Productivity Tools**: Startups like Anthropic are developing AI agents capable of performing routine tasks across different applications, aiming to streamline workflows and reduce the need for multiple apps. ([ft.com](https://www.ft.com/content/a0e54dd5-b270-42cc-8c4c-18a0b8b3e6cc?utm_source=openai))

- **Read AI's Expansion**: Read AI, a productivity startup, secured $50 million in funding, valuing the company at $450 m

Trong ví dụ này, chúng ta đã tạo một trợ lý nghiên cứu có thể tìm kiếm web và tổng hợp thông tin thành bản tóm tắt mạch lạc. WebSearchTool không cần tham số để hoạt động, nhưng bạn có thể tùy chỉnh hành vi của nó nếu cần:

# Customized search tool with location context
location_aware_search = WebSearchTool(
   user_location="San Francisco, CA",  # Provides geographic context for local search queries
   search_context_size=3  # Number of search results to consider in the response
)

Tham số user_location đặc biệt hữu ích cho các truy vấn hưởng lợi từ ngữ cảnh địa lý, như dịch vụ địa phương hoặc thông tin khu vực. Tham số search_context_size giúp kiểm soát số lượng kết quả tìm kiếm mà mô hình cân nhắc khi xây dựng phản hồi.

Công cụ hàm (Function tools)

Công cụ hàm cho phép bạn mở rộng agent với bất kỳ hàm Python nào. Đây là nơi tính linh hoạt thực sự của Agents SDK tỏa sáng, cho phép tích hợp với bất kỳ API, cơ sở dữ liệu hoặc dịch vụ cục bộ nào.

Công cụ dự báo thời tiết

Hãy tạo một ví dụ thực tế tích hợp với API thời tiết bên thứ ba:

import os
import requests
from datetime import datetime
from typing import Optional, List
from dataclasses import dataclass

from agents import Agent, Runner, function_tool
from dotenv import load_dotenv

load_dotenv()


@dataclass
class WeatherInfo:
   temperature: float
   feels_like: float
   humidity: int
   description: str
   wind_speed: float
   pressure: int
   location_name: str
   rain_1h: Optional[float] = None
   visibility: Optional[int] = None


@function_tool
def get_weather(lat: float, lon: float) -> str:
   """Get the current weather for a specified location using OpenWeatherMap API.

   Args:
       lat: Latitude of the location (-90 to 90)
       lon: Longitude of the location (-180 to 180)
   """
   # Get API key from environment variables
   WEATHER_API_KEY = os.getenv("OPENWEATHERMAP_API_KEY")

   # Build URL with parameters
   url = f"https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={WEATHER_API_KEY}&units=metric"

   try:
       response = requests.get(url)
       response.raise_for_status()
       data = response.json()

       # Extract weather data from the response
       weather_info = WeatherInfo(
           temperature=data["main"]["temp"],
           feels_like=data["main"]["feels_like"],
           humidity=data["main"]["humidity"],
           description=data["weather"][0]["description"],
           wind_speed=data["wind"]["speed"],
           pressure=data["main"]["pressure"],
           location_name=data["name"],
           visibility=data.get("visibility"),
           rain_1h=data.get("rain", {}).get("1h"),
       )

       # Build the response string
       weather_report = f"""
       Weather in {weather_info.location_name}:
       - Temperature: {weather_info.temperature}°C (feels like {weather_info.feels_like}°C)
       - Conditions: {weather_info.description}
       - Humidity: {weather_info.humidity}%
       - Wind speed: {weather_info.wind_speed} m/s
       - Pressure: {weather_info.pressure} hPa
       """
       return weather_report

   except requests.exceptions.RequestException as e:
       return f"Error fetching weather data: {str(e)}"

Công cụ hàm API thời tiết này đóng vai trò cầu nối giữa OpenWeatherMap API và agent của chúng ta. Nó truy xuất dữ liệu thời tiết theo thời gian thực bằng tọa độ địa lý và định dạng thành báo cáo dễ đọc. 

Mã định nghĩa một lớp dữ liệu WeatherInfo để cấu trúc dữ liệu với các trường có kiểu (nhiệt độ, độ ẩm, v.v.), giúp có tổ chức và dễ bảo trì. Decorator @function_tool biến hàm Python của chúng ta thành một công cụ mà agent có thể dùng, tự động tạo schema từ chữ ký hàm và docstring.

Khi được gọi, hàm sẽ truy xuất khóa API an toàn từ biến môi trường, gửi yêu cầu HTTP tới OpenWeatherMap và xử lý phản hồi JSON. 

Hàm xử lý an toàn các trường dữ liệu tùy chọn như lượng mưa và định dạng mọi thứ thành báo cáo thời tiết rõ ràng, bao gồm cả xử lý lỗi nếu yêu cầu API thất bại. Điều này cho phép agent cung cấp thông tin thời tiết hiện tại ở định dạng nhất quán, dễ đọc mà không cần hiểu chi tiết API.

# Create a weather assistant
weather_assistant = Agent(
   name="Weather Assistant",
   instructions="""You are a weather assistant that can provide current weather information.
  
   When asked about weather, use the get_weather tool to fetch accurate data.
   If the user doesn't specify a country code and there might be ambiguity,
   ask for clarification (e.g., Paris, France vs. Paris, Texas).
  
   Provide friendly commentary along with the weather data, such as clothing suggestions
   or activity recommendations based on the conditions.
   """,
   tools=[get_weather]
)

Để chạy trợ lý thời tiết:

async def main():
   runner = Runner()
  
   simple_request = await runner.run(weather_assistant, "What are your capabilities?")
  
   request_with_location = await runner.run(weather_assistant, "What's the weather like in Tashkent right now?")
  
   print(simple_request.final_output)
   print("-"*70)
   print(request_with_location.final_output)

await main()

Output:

I can provide you with the current weather conditions for any location around the world. Just give me the location details, and I'll fetch the weather data for you. I can also offer tips on activities or clothing based on the weather. If you have a specific city in mind, let me know, and I'll get to work!
----------------------------------------------------------------------
The weather in Tashkent is currently lovely with a clear sky. It's around 19.8°C, but it might feel slightly cooler at 18.6°C. The humidity is quite low at 26%, making it a pleasant day to be outdoors. A gentle breeze is blowing at 3.09 m/s, and the air pressure is steady at 1023 hPa.

It's a great time for a picnic in the park or a leisurely walk. Light clothing should be perfect for this weather. Enjoy your day in Tashkent!

Phản hồi cho thấy agent đã sử dụng công cụ thời tiết thành công. Nó tách được tên thành phố từ lời nhắc, dùng kiến thức của chính nó để lấy tọa độ, và truyền chúng làm lat và lon cho công cụ.

Agent như công cụ

Agents SDK cho phép bạn sử dụng chính các agent như công cụ, cho phép cấu trúc phân cấp nơi các agent chuyên gia làm việc dưới sự điều phối của điều phối viên. Đây là mẫu mạnh mẽ cho quy trình phức tạp.

from agents import Agent, Runner
from dotenv import load_dotenv

load_dotenv()

# Specialist agents
note_taking_agent = Agent(
   name="Note Manager",
   instructions="You help users take and organize notes efficiently.",
   # In a real application, this agent would have note-taking tools
)

task_management_agent = Agent(
   name="Task Manager",
   instructions="You help users manage tasks, deadlines, and priorities.",
   # In a real application, this agent would have task management tools
)

# Coordinator agent that uses specialists as tools
productivity_assistant = Agent(
   name="Productivity Assistant",
   instructions="""You are a productivity assistant that helps users organize their work and personal life.
  
   For note-taking questions or requests, use the note_taking tool.
   For task and deadline management, use the task_management tool.
  
   Help the user decide which tool is appropriate based on their request,
   and coordinate between different aspects of productivity.
   """,
   tools=[
       note_taking_agent.as_tool(
           tool_name="note_taking",
           tool_description="For taking, organizing, and retrieving notes and information"
       ),
       task_management_agent.as_tool(
           tool_name="task_management",
           tool_description="For managing tasks, setting deadlines, and tracking priorities"
       )
   ]
)

Trong ví dụ này:

1. Chúng ta tạo hai agent chuyên biệt, mỗi agent có một miền chuyên môn tập trung.
2. Sau đó tạo một agent điều phối có thể ủy quyền cho các chuyên gia này.
3. Chúng ta chuyển mỗi agent chuyên gia thành một công cụ bằng phương thức .as_tool(), chỉ định:

• tool_name mà điều phối viên sẽ dùng để tham chiếu công cụ.
• tool_description giúp điều phối viên hiểu khi nào nên dùng công cụ này.

Mẫu này cho phép bạn tạo hệ thống agent phức tạp đồng thời duy trì nguyên tắc phân tách mối quan tâm. Mỗi agent chuyên biệt có thể có bộ công cụ và chuyên môn riêng, trong khi điều phối viên quản lý tương tác với người dùng và ủy quyền cho chuyên gia phù hợp.

Để sử dụng trợ lý năng suất:

async def main():
   runner = Runner()
  
   result = await runner.run(productivity_assistant, "I need to keep track of my project deadlines")
   print(result.final_output)

await main()

Công cụ biến agent từ trợ lý hội thoại đơn thuần thành hệ thống mạnh mẽ có khả năng thực hiện các hành động ý nghĩa trong thế giới thực. Mặc dù chúng ta đã bao quát những điều cơ bản về tạo và sử dụng công cụ, đây chỉ là khởi đầu cho những gì có thể. Với cách dùng nâng cao, bao gồm xử lý lỗi trong công cụ hàm, hãy tham khảo tài liệu chính thức.

Giờ chúng ta đã hiểu cách trang bị công cụ cho agent, thách thức tiếp theo là xử lý và cấu trúc đầu ra của chúng. Ở phần tiếp theo, chúng ta sẽ khám phá kỹ thuật xử lý phản hồi của agent, từ văn bản cơ bản đến dữ liệu có cấu trúc phức tạp, đảm bảo nhận được đúng định dạng thông tin mà ứng dụng cần.

Hiểu đầu ra của OpenAI Agent

Khi làm việc với agent, nhận thông tin có cấu trúc thay vì văn bản tự do có thể giúp ứng dụng của bạn đáng tin cậy hơn. OpenAI Agents SDK cung cấp cách tích hợp, rõ ràng để nhận đầu ra có cấu trúc trực tiếp từ agent.

Đầu ra có cấu trúc với mô hình Pydantic

SDK cho phép bạn định nghĩa chính xác cấu trúc dữ liệu bạn muốn agent trả về bằng cách chỉ định tham số output_type khi tạo agent:

from pydantic import BaseModel
from typing import List, Optional
from agents import Agent, Runner
from dotenv import load_dotenv

load_dotenv()
True
First, we define our data models using Pydantic:
# Define person data model
class Person(BaseModel):
   name: str
   role: Optional[str]
   contact: Optional[str]


# Define meeting data model
class Meeting(BaseModel):
   date: str
   time: str
   location: Optional[str]
   duration: Optional[str]


# Define task data model
class Task(BaseModel):
   description: str
   assignee: Optional[str]
   deadline: Optional[str]
   priority: Optional[str]


# Define the complete email data model
class EmailData(BaseModel):
   subject: str
   sender: Person
   recipients: List[Person]
   main_points: List[str]
   meetings: List[Meeting]
   tasks: List[Task]
   next_steps: Optional[str]

Các mô hình này xác định cấu trúc chúng ta muốn dữ liệu trích xuất tuân theo. Mỗi lớp đại diện cho một loại thông tin cụ thể chúng ta muốn trích xuất từ email.

Giờ, chúng ta tạo một agent sẽ xuất dữ liệu theo định dạng có cấu trúc bằng cách đặt tham số output_type:

# Create an email extraction agent with structured output
email_extractor = Agent(
   name="Email Extractor",
   instructions="""You are an assistant that extracts structured information from emails.
  
   When given an email, carefully identify:
   - Subject and main points
   - People mentioned (names, roles, contact info)
   - Meetings (dates, times, locations)
   - Tasks or action items (with assignees and deadlines)
   - Next steps or follow-ups
  
   Extract this information as structured data. If something is unclear or not mentioned,
   leave those fields empty rather than making assumptions.
   """,
   output_type=EmailData,  # This tells the agent to return data in EmailData format
)

Khi bạn chỉ định output_type, agent sẽ tự động tạo dữ liệu có cấu trúc thay vì phản hồi dạng văn bản thuần. Điều này loại bỏ nhu cầu phải tự phân tích JSON thủ công hoặc dùng regex.

Hãy dùng bộ trích xuất này với một email mẫu:

sample_email = """
From: Alex Johnson <alex.j@techcorp.com>
To: Team Development <team-dev@techcorp.com>
CC: Sarah Wong <sarah.w@techcorp.com>, Miguel Fernandez <miguel.f@techcorp.com>
Subject: Project Phoenix Update and Next Steps

Hi team,

I wanted to follow up on yesterday's discussion about Project Phoenix and outline our next steps.

Key points from our discussion:
- The beta testing phase has shown promising results with 85% positive feedback
- We're still facing some performance issues on mobile devices
- The client has requested additional features for the dashboard

Let's schedule a follow-up meeting this Friday, June 15th at 2:00 PM in Conference Room B. The meeting should last about 1.5 hours, and we'll need to prepare the updated project timeline.

Action items:
1. Sarah to address the mobile performance issues by June 20th (High priority)
2. Miguel to create mock-ups for the new dashboard features by next Monday
3. Everyone to review the beta testing feedback document and add comments by EOD tomorrow

If you have any questions before Friday's meeting, feel free to reach out.

Best regards,
Alex Johnson
Senior Project Manager
(555) 123-4567
"""

Giờ việc xử lý email trở nên đơn giản hơn nhiều vì SDK đảm nhiệm việc chuyển đổi:

async def process_email(email_text):
   runner = Runner()
   result = await runner.run(
       email_extractor,
       f"Please extract information from this email:\n\n{email_text}"
   )

   # The result is already a structured EmailData object
   return result


# Process the sample email
result = await process_email(sample_email)

# Display the extracted information
result = result.final_output

print(f"Subject: {result.subject}")
print(f"From: {result.sender.name} ({result.sender.role})")
print("\nMain points:")
for point in result.main_points:
   print(f"- {point}")

print("\nMeetings:")
for meeting in result.meetings:
   print(f"- {meeting.date} at {meeting.time}, Location: {meeting.location}")

print("\nTasks:")
for task in result.tasks:
   print(f"- {task.description}")
   print(
       f"  Assignee: {task.assignee}, Deadline: {task.deadline}, Priority: {task.priority}"
   )
—----------

Subject: Project Phoenix Update and Next Steps
From: Alex Johnson (Senior Project Manager)

Main points:
- 85% positive feedback from beta testing
- Performance issues on mobile devices
- Client requested additional dashboard features

Meetings:
- June 15th at 2:00 PM, Location: Conference Room B

Tasks:
- Address mobile performance issues
 Assignee: Sarah, Deadline: June 20th, Priority: High
- Create mock-ups for new dashboard features
 Assignee: Miguel, Deadline: Next Monday, Priority: None
- Review beta testing feedback document and add comments
 Assignee: Everyone, Deadline: EOD tomorrow, Priority: None

Đoạn mã này gọn gàng hơn nhiều so với cách tiếp cận trước vì:

1. Chúng ta không cần tự trích xuất và phân tích JSON từ phản hồi.
2. SDK xử lý việc chuyển đổi từ đầu ra của agent sang mô hình Pydantic.
3. Chúng ta có thể truy cập trực tiếp các thuộc tính dữ liệu có cấu trúc (như result.final_output.subject).
4. Kiểm tra kiểu diễn ra tự động, nên chúng ta biết dữ liệu khớp với mô hình.

Làm việc với các loại đầu ra khác nhau

Tham số output_type hoạt động với mọi kiểu có thể được bao bọc bởi TypeAdapter của Pydantic:

# For simple lists
agent_with_list_output = Agent(
   name="List Generator",
   instructions="Generate lists of items based on the user's request.",
   output_type=list[str],  # Returns a list of strings
)

# For dictionaries
agent_with_dict_output = Agent(
   name="Dictionary Generator",
   instructions="Create key-value pairs based on the input.",
   output_type=dict[
       str, int
   ],  # Returns a dictionary with string keys and integer values
)

# For simple primitive types
agent_with_bool_output = Agent(
   name="Decision Maker",
   instructions="Answer yes/no questions with True or False.",
   output_type=bool,  # Returns a boolean
)

Lợi ích của đầu ra có cấu trúc

Sử dụng tham số output_type mang lại nhiều lợi thế:

1. Tích hợp trực tiếp: Đầu ra của agent tự động có sẵn dưới dạng đối tượng Python.
2. An toàn kiểu: SDK đảm bảo đầu ra khớp với cấu trúc bạn định nghĩa.
3. Mã đơn giản hơn: Không cần phân tích JSON thủ công hoặc xử lý lỗi.
4. Hiệu năng tốt hơn: SDK xử lý chuyển đổi hiệu quả.
5. Hỗ trợ IDE: IDE có thể gợi ý tự động cho các thuộc tính đầu ra có cấu trúc.

Bằng cách định nghĩa các mô hình dữ liệu rõ ràng và sử dụng tham số output_type, agent của bạn có thể tạo chính xác cấu trúc dữ liệu mà ứng dụng cần, giúp tích hợp liền mạch và giảm độ phức tạp của mã.

Ở phần tiếp theo, chúng ta sẽ khám phá handoff giữa các agent, cho phép bạn tạo các agent chuyên biệt có thể phối hợp xử lý tác vụ phức tạp. Các handoff này có thể dùng đầu ra có cấu trúc để truyền thông tin giữa các agent một cách nhất quán, an toàn về kiểu.

Handoff: Ủy quyền giữa các agent

Trong các ứng dụng phức tạp, những nhiệm vụ khác nhau thường đòi hỏi các lĩnh vực chuyên môn khác nhau. OpenAI Agents SDK hỗ trợ “handoff”, cho phép một agent chuyển giao quyền kiểm soát cho agent chuyên biệt khác. Tính năng này đặc biệt giá trị khi xây dựng hệ thống xử lý đa dạng yêu cầu người dùng, như ứng dụng hỗ trợ khách hàng nơi các agent khác nhau có thể xử lý câu hỏi thanh toán, hỗ trợ kỹ thuật, hoặc quản lý tài khoản.

Tạo handoff cơ bản

Ở mức đơn giản nhất, handoff cho phép bạn kết nối nhiều agent để chúng có thể chuyển giao khi phù hợp. Hãy tạo một hệ thống chăm sóc khách hàng đơn giản với agent tiếp nhận có thể handoff cho chuyên gia:

from agents import Agent, handoff, Runner
from dotenv import load_dotenv

load_dotenv()

# Create specialist agents
billing_agent = Agent(
   name="Billing Agent",
   instructions="""You are a billing specialist who helps customers with payment issues.
   Focus on resolving billing inquiries, subscription changes, and refund requests.
   If asked about technical problems or account settings, explain that you specialize
   in billing and payment matters only.""",
)

technical_agent = Agent(
   name="Technical Agent",
   instructions="""You are a technical support specialist who helps with product issues.
   Assist users with troubleshooting, error messages, and how-to questions.
   Focus on resolving technical problems only.""",
)

# Create a triage agent that can hand off to specialists
triage_agent = Agent(
   name="Customer Service",
   instructions="""You are the initial customer service contact who helps direct
   customers to the right specialist.
  
   If the customer has billing or payment questions, hand off to the Billing Agent.
   If the customer has technical problems or how-to questions, hand off to the Technical Agent.
   For general inquiries or questions about products, you can answer directly.
  
   Always be polite and helpful, and ensure a smooth transition when handing off to specialists.""",
   handoffs=[billing_agent, technical_agent],  # Direct handoff to specialist agents
)

Trong ví dụ này, chúng ta tạo hệ thống với ba agent:

• Hai agent chuyên biệt với chuyên môn tập trung
• Một agent tiếp nhận có thể ủy quyền cho các chuyên gia

Lưu ý cách chúng ta chỉ cần đưa các agent chuyên gia vào tham số handoffs của agent tiếp nhận. Agents SDK sẽ tự động tạo các công cụ handoff phù hợp để agent tiếp nhận có thể dùng khi cần.

Hãy xem hệ thống hoạt động:

async def handle_customer_request(request):
   runner = Runner()
   result = await runner.run(triage_agent, request)
   return result


# Example customer inquiries
billing_inquiry = (
   "I was charged twice for my subscription last month. Can I get a refund?"
)
technical_inquiry = (
   "The app keeps crashing when I try to upload photos. How can I fix this? Give me the shortest solution possible."
)
general_inquiry = "What are your business hours?"

# Process the different types of inquiries
billing_response = await handle_customer_request(billing_inquiry)
print(f"Billing inquiry response:\n{billing_response.final_output}\n")

technical_response = await handle_customer_request(technical_inquiry)
print(f"Technical inquiry response:\n{technical_response.final_output}\n")

general_response = await handle_customer_request(general_inquiry)
print(f"General inquiry response:\n{general_response.final_output}")

Khi agent tiếp nhận nhận câu hỏi thanh toán, nó sẽ nhận ra Billing Agent phù hợp hơn để xử lý và sẽ kích hoạt handoff. Câu hỏi kỹ thuật sẽ được chuyển cho technical agent. Agent sẽ trả lời trực tiếp các câu hỏi chung trong phạm vi khả năng. Dưới đây là đầu ra:

Billing inquiry response:
I can help with that. Could you please provide the transaction details or the date of the charges? This will help me locate the duplicate charge and process a refund for you.

Technical inquiry response:
Try these steps:

1. Restart the app.
2. Update to the latest app version.
3. Clear the app cache.
4. Restart your device.

If it persists, reinstall the app.

General inquiry response:
Our business hours are Monday to Friday, 9 AM to 5 PM. If you need assistance outside these hours, feel free to reach out and we'll get back to you as soon as possible. Is there anything else I can help you with?

Tùy chỉnh handoff

Để kiểm soát nhiều hơn đối với handoff, bạn có thể sử dụng hàm handoff() thay vì truyền agent trực tiếp vào tham số handoffs:

from agents import Agent, handoff, RunContextWrapper
from datetime import datetime

# Create an agent that handles account-related questions
account_agent = Agent(
   name="Account Management",
   instructions="""You help customers with account-related issues such as
   password resets, account settings, and profile updates.""",
)


# Custom handoff callback function
async def log_account_handoff(ctx: RunContextWrapper[None]):
   print(
       f"[LOG] Account handoff triggered at {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}"
   )
   # In a real app, you might log to a database or alert a human supervisor


# Create a triage agent with customized handoffs
enhanced_triage_agent = Agent(
   name="Enhanced Customer Service",
   instructions="""You are the initial customer service contact who directs
   customers to the right specialist.
  
   If the customer has billing or payment questions, hand off to the Billing Agent.
   If the customer has technical problems, hand off to the Technical Agent.
   If the customer needs to change account settings, hand off to the Account Management agent.
   For general inquiries, you can answer directly.""",
   handoffs=[
       billing_agent,  # Basic handoff
       handoff(  # Customized handoff
           agent=account_agent,
           on_handoff=log_account_handoff,  # Callback function
           tool_name_override="escalate_to_account_team",  # Custom tool name
           tool_description_override="Transfer the customer to the account management team for help with account settings, password resets, etc.",
       ),
       technical_agent,  # Basic handoff
   ],
)

result = await Runner.run(
   enhanced_triage_agent, "I need to change my password."
)

Đầu ra:

[LOG] Account handoff triggered at 2025-03-16 17:45:48

Hàm handoff() cho phép bạn:

• Chỉ định callback tùy chỉnh với on_handoff
• Ghi đè tên công cụ mặc định (thông thường là “transfer_to_[agent_name]”)
• Cung cấp mô tả công cụ tùy chỉnh
• Cấu hình xử lý đầu vào (sẽ nói thêm bên dưới)

Truyền dữ liệu trong quá trình handoff

Đôi khi, bạn muốn agent đầu tiên cung cấp thêm ngữ cảnh hoặc siêu dữ liệu khi chuyển giao cho agent khác. Agents SDK hỗ trợ điều này thông qua tham số input_type:

from pydantic import BaseModel
from typing import Optional
from agents import Agent, handoff, RunContextWrapper


# Define the data structure to pass during handoff
class EscalationData(BaseModel):
   reason: str
   priority: Optional[str]
   customer_tier: Optional[str]


# Handoff callback that processes the escalation data
async def process_escalation(ctx: RunContextWrapper, input_data: EscalationData):
   print(f"[ESCALATION] Reason: {input_data.reason}")
   print(f"[ESCALATION] Priority: {input_data.priority}")
   print(f"[ESCALATION] Customer tier: {input_data.customer_tier}")

   # You might use this data to prioritize responses, alert human agents, etc.


# Create an escalation agent
escalation_agent = Agent(
   name="Escalation Agent",
   instructions="""You handle complex or sensitive customer issues that require
   special attention. Always address the customer's concerns with extra care and detail.""",
)

# Create a service agent that can escalate with context
service_agent = Agent(
   name="Service Agent",
   instructions="""You are a customer service agent who handles general inquiries.
  
   For complex issues, escalate to the Escalation Agent and provide:
   - The reason for escalation
   - Priority level (Low, Normal, High, Urgent)
   - Customer tier if mentioned (Standard, Premium, VIP)""",
   handoffs=[
       handoff(
           agent=escalation_agent,
           on_handoff=process_escalation,
           input_type=EscalationData,
       )
   ],
)

Với thiết lập này, khi service agent quyết định handoff cho escalation agent, nó sẽ cung cấp dữ liệu có cấu trúc về lý do leo thang. Hệ thống sẽ xác thực dữ liệu này theo mô hình EscalationData trước khi chuyển tới callback process_escalation.

Khi nào dùng handoff so với agent-như-công-cụ

Agents SDK cung cấp hai cách để các agent làm việc cùng nhau: handoff và dùng agent như công cụ (như chúng ta đã thấy ở phần trước). Dưới đây là khi nào dùng mỗi cách:

Dùng handoff khi:

• Bạn muốn chuyển giao hoàn toàn quyền kiểm soát cho agent khác
• Cuộc hội thoại cần tiếp tục với chuyên gia
• Bạn xây dựng quy trình làm việc nơi các agent khác nhau xử lý các giai đoạn khác nhau

Dùng agent-như-công-cụ khi:

• Agent chính cần tham vấn chuyên gia nhưng vẫn giữ quyền kiểm soát
• Bạn muốn đưa phản hồi của chuyên gia vào một câu trả lời lớn hơn
• Bạn xây dựng hệ thống phân cấp nơi điều phối viên ủy quyền các tiểu nhiệm vụ

Cả hai cách có thể kết hợp trong hệ thống tinh vi, với agent chính đôi khi tham vấn chuyên gia (dùng họ như công cụ) và đôi khi chuyển giao hoàn toàn khi phù hợp.

Handoff cung cấp cơ chế mạnh mẽ để xây dựng hệ thống agent phức tạp nơi trách nhiệm chuyển giao giữa các chuyên gia khác nhau. Khi thiết kế kiến trúc agent, hãy cân nhắc cách nào phù hợp nhất với trường hợp sử dụng cụ thể của bạn để tạo trải nghiệm người dùng hiệu quả nhất.

Kết luận và Bước tiếp theo

Chúng ta đã khám phá các thành phần cốt lõi của OpenAI Agents SDK, từ tạo agent cơ bản đến triển khai công cụ hàm và quản lý handoff giữa các agent chuyên biệt. Chúng ta đã thấy cách đầu ra có cấu trúc bằng mô hình Pydantic giúp ứng dụng đáng tin cậy và dễ bảo trì hơn, và cách thiết kế hệ thống agent có thể xử lý tác vụ phức tạp thông qua ủy quyền và chuyên môn hóa.

Tuy nhiên, chúng ta mới chỉ chạm bề mặt những gì có thể với khung mạnh mẽ này. Với các nhà phát triển sẵn sàng đưa hệ thống agent lên tầm cao mới, còn nhiều chủ đề nâng cao chờ khám phá: phản hồi dạng streaming cho cập nhật theo thời gian thực, tracing và khả năng quan sát để gỡ lỗi, điều phối đa agent cho quy trình phức tạp, quản lý ngữ cảnh để duy trì trạng thái hội thoại, và guardrail để đảm bảo hành vi an toàn và phù hợp của agent.

Khi AI agent ngày càng trở nên trung tâm của các ứng dụng hiện đại, những kỹ năng bạn đã phát triển qua hướng dẫn này sẽ là nền tảng vững chắc để tạo hệ thống AI tinh vi. Hãy tiếp tục hành trình học tập với các tài nguyên như Hướng dẫn học AI của DataCamp, và hãy nhớ rằng thiết kế agent hiệu quả vừa là nghệ thuật vừa là khoa học — đòi hỏi lặp lại, thử nghiệm, và hiểu sâu nhu cầu người dùng cũng như khả năng của AI.