Cách Sử Dụng SDK của Các Ajent OpenAI?

OpenAI Agents SDK là một thư viện Python được thiết kế để đơn giản hóa việc phát triển các tác nhân AI được powered by các mô hình ngôn ngữ của OpenAI. Nó cung cấp cho các nhà phát triển các công cụ để tạo ra các tác nhân chuyên biệt cho nhiệm vụ, tích hợp chức năng bên ngoài, quản lý việc phân công nhiệm vụ giữa các tác nhân, thực thi xác thực đầu vào/đầu ra và theo dõi luồng thực thi. Hướng dẫn này cung cấp một hướng dẫn chi tiết, kỹ thuật về việc cài đặt, cấu hình và sử dụng SDK một cách hiệu quả, đảm bảo ít nhất 2000 từ với trọng tâm là chính xác và ứng dụng thực tiễn.

💡

Trước khi bắt đầu, đây là một mẹo nhanh: Vì chúng tôi sẽ làm việc với API rất nhiều trong hướng dẫn này, bạn có thể muốn lấy Apidog. Đây là một công cụ miễn phí giúp việc kiểm tra và gỡ lỗi API trở nên siêu dễ dàng, hoàn hảo cho việc thử nghiệm với OpenAI Agents SDK. Bạn có thể tải xuống Apidog miễn phí ở đây. Tin tôi đi, nó sẽ giúp bạn tiết kiệm khá nhiều đau đầu!

button

Giới thiệu

OpenAI Agents SDK cung cấp một cấu trúc có tổ chức để xây dựng các hệ thống đa tác nhân, trong đó mỗi tác nhân được thiết kế để thực hiện các nhiệm vụ cụ thể. Những tác nhân này có thể tương tác với người dùng, thực thi các hành động thông qua các công cụ tích hợp và cộng tác bằng cách chuyển giao nhiệm vụ cho các tác nhân khác. Những thành phần chính của SDK bao gồm:

Tác nhân: Các cInstance của mô hình ngôn ngữ được cấu hình với các hướng dẫn và vai trò cụ thể.
Công cụ: Các hàm hoặc dịch vụ (ví dụ: tìm kiếm web, mã Python tùy chỉnh) mở rộng khả năng của tác nhân.
Chuyển giao: Các cơ chế cho phép các tác nhân phân công nhiệm vụ cho các tác nhân khác một cách liền mạch.
Rào chắn: Các lớp xác thực để đảm bảo các đầu vào và đầu ra đáp ứng các tiêu chí đã định nghĩa.
Ghi lại: Các nhật ký thực thi để gỡ lỗi và phân tích hiệu suất.

Hướng dẫn này được thiết kế cho các nhà phát triển có hiểu biết cơ bản về Python và các tương tác API, cung cấp các giải thích chi tiết, ví dụ mã và các phương pháp tốt nhất để tạo ra một tài nguyên mạnh mẽ và toàn diện.

Cài đặt và Cấu hình

Cài đặt đúng là rất quan trọng để sử dụng OpenAI Agents SDK một cách hiệu quả. Phần này đề cập đến các yêu cầu trước, thiết lập môi trường, cài đặt và xác minh.

Yêu cầu trước

Trước khi tiếp tục, hãy đảm bảo các điều sau:

Python 3.8+: Kiểm tra phiên bản Python của bạn với python --version. Cài đặt từ python.org nếu cần.

Khóa API của OpenAI: Nhận khóa của bạn từ platform.openai.com dưới cài đặt tài khoản của bạn. Khóa này xác thực các yêu cầu đến máy chủ của OpenAI.

Bước 1: Thiết lập Môi trường Ảo

Một môi trường ảo cách ly các phụ thuộc của dự án, ngăn chặn xung đột với các dự án Python khác. Để tạo và kích hoạt một môi trường:

Linux/macOS:

python -m venv agents_env
source agents_env/bin/activate

Windows:

python -m venv agents_env
agents_env\Scripts\activate

Ngay khi được kích hoạt, dấu nhắc terminal của bạn nên phản ánh môi trường (ví dụ, (agents_env)). Bước này là một thực tế tốt trong phát triển Python, đảm bảo không gian làm việc sạch sẽ.

Bước 2: Cài đặt SDK

Với môi trường ảo được kích hoạt, cài đặt SDK bằng pip:

pip install openai-agents

Lệnh này lấy phiên bản mới nhất của SDK và các phụ thuộc của nó từ PyPI. Để xác nhận việc cài đặt, chạy:

pip show openai-agents-python

Lệnh này hiển thị siêu dữ liệu, bao gồm cả số phiên bản, xác nhận rằng gói đã được cài đặt.

Bước 3: Cấu hình Khóa API

SDK yêu cầu một khóa API của OpenAI để hoạt động. Đặt nó làm biến môi trường để tránh nhúng nó vào mã của bạn, điều này cải thiện bảo mật:

Linux/macOS:

export OPENAI_API_KEY='your-api-key'

Windows:

set OPENAI_API_KEY='your-api-key'

Để giữ cho biến này tồn tại giữa các phiên làm việc, hãy thêm lệnh vào tệp cấu hình shell của bạn (ví dụ, .bashrc hoặc .zshrc trên hệ thống Unix). Ngoài ra, bạn có thể thiết lập nó trong mã Python, mặc dù điều này ít an toàn hơn:

import os
os.environ["OPENAI_API_KEY"] = "your-api-key"

Bước 4: Xác minh Việc Cài đặt

Kiểm tra cài đặt với một tác nhân tối thiểu để đảm bảo mọi thứ hoạt động:

from agents import Agent, Runner

agent = Agent(name="TestAgent", instructions="Return 'Setup successful'")
result = Runner.run_sync(agent, "Run test")
print(result.final_output)  # Kết quả mong đợi: "Setup successful"

Nếu điều này in ra "Setup successful," việc cài đặt của bạn là hợp lệ. Các vấn đề thường gặp bao gồm:

Khóa API không hợp lệ: Kiểm tra kỹ khóa và đảm bảo không có khoảng trắng hay lỗi chính tả nào.
Lỗi Mạng: Xác minh kết nối Internet của bạn và trạng thái máy chủ của OpenAI.

Tạo Tác Nhân

Các tác nhân là các khối xây dựng cơ bản của SDK, mỗi tác nhân được xác định bởi một vai trò và hành vi độc đáo.

Khởi Tạo Tác Nhân

Class Agent được sử dụng để khởi tạo các tác nhân. Các tham số chính bao gồm:

name: Một định danh chuỗi (ví dụ: "MathAgent").
instructions: Một chuỗi xác định mục đích của tác nhân (ví dụ: "Giải các bài toán toán học").
model: Mô hình OpenAI để sử dụng (mặc định: gpt-4).
temperature: Một số thực từ 0 đến 1 điều khiển độ ngẫu nhiên của đầu ra (mặc định: 0.7).

Ví Dụ: Tác Nhân Cơ Bản

Dưới đây là một tác nhân đơn giản cho phép tính:

from agents import Agent, Runner

agent = Agent(
    name="MathAgent",
    instructions="Solve arithmetic expressions."
)
result = Runner.run_sync(agent, "Calculate 10 * 2")
print(result.final_output)  # Kết quả: "20"

Phương thức Runner.run_sync thực thi tác nhân theo cách đồng bộ, trả về một đối tượng kết quả với thuộc tính final_output.

Cấu Hình Nâng Cao

Tùy chỉnh các tác nhân cho các nhu cầu cụ thể bằng cách điều chỉnh các tham số:

agent = Agent(
    name="CreativeWriter",
    instructions="Write a short story based on the prompt.",
    model="gpt-4",
    temperature=0.9
)
result = Runner.run_sync(agent, "A robot in a distant galaxy")
print(result.final_output)  # Kết quả: Một câu chuyện sáng tạo

Mô hình: gpt-4 cung cấp suy nghĩ vượt trội, trong khi gpt-3.5-turbo nhanh hơn và rẻ hơn cho các nhiệm vụ đơn giản hơn.
Nhiệt độ: Các giá trị thấp hơn (ví dụ: 0.2) tạo ra các đầu ra dự đoán; các giá trị cao hơn (ví dụ: 0.9) tăng sự sáng tạo.

Ví Dụ Nhiều Tác Nhân

Tạo các tác nhân riêng biệt cho các nhiệm vụ khác nhau:

support_agent = Agent(
    name="SupportBot",
    instructions="Answer technical support questions."
)
code_agent = Agent(
    name="CodeHelper",
    instructions="Generate Python code snippets."
)

support_result = Runner.run_sync(support_agent, "How do I install Python?")
code_result = Runner.run_sync(code_agent, "Write a function to add two numbers")
print(support_result.final_output)  # Kết quả: Hướng dẫn cài đặt
print(code_result.final_output)     # Kết quả: "def add(a, b): return a + b"

Điều này chứng minh tính linh hoạt của SDK trong việc xử lý các vai trò đa dạng.

Tích Hợp Công Cụ

Các công cụ tăng cường khả năng của tác nhân bằng cách cho phép chúng thực hiện các hành động bên ngoài. SDK hỗ trợ các công cụ được lưu trữ, công cụ hàm tùy chỉnh và công cụ dựa trên tác nhân.

Sử Dụng Công Cụ Được Lưu Trữ

Các công cụ được lưu trữ, như web_search, được xây dựng sẵn và sẵn sàng để sử dụng:

from agents import Agent, Runner, web_search

agent = Agent(
    name="ResearchAgent",
    instructions="Answer questions using web search.",
    tools=[web_search]
)
result = Runner.run_sync(agent, "What is the capital of France?")
print(result.final_output)  # Kết quả: "Thủ đô của Pháp là Paris."

Tác nhân tự động gọi web_search để lấy dữ liệu theo thời gian thực.

Tạo Công Cụ Hàm Tùy Chỉnh

Xác định các công cụ tùy chỉnh với bộ định nghĩa @function_tool. Các công cụ phải chấp nhận và trả về chuỗi.

Ví Dụ: Công Cụ Lấy Dữ Liệu

from agents import Agent, Runner, function_tool

@function_tool
def fetch_data(id: str) -> str:
    """Trả về dữ liệu cho ID đã cho."""
    # Tìm kiếm trong cơ sở dữ liệu mô phỏng
    return f"Dữ liệu cho ID {id}: hoạt động"

agent = Agent(
    name="DataAgent",
    instructions="Retrieve data using the tool.",
    tools=[fetch_data]
)
result = Runner.run_sync(agent, "Fetch data for ID 123")
print(result.final_output)  # Kết quả: "Dữ liệu cho ID 123: hoạt động"

Tích Hợp Các API Bên Ngoài

Các công cụ có thể kết nối với các dịch vụ bên ngoài. Đây là một ví dụ về công cụ thời tiết:

import requests
from agents import function_tool, Agent, Runner

@function_tool
def get_weather(city: str) -> str:
    """Lấy thời tiết hiện tại cho một thành phố."""
    api_key = "your-weather-api-key"  # Thay thế bằng một khóa thực
    url = f"http://api.weatherapi.com/v1/current.json?key={api_key}&q={city}"
    response = requests.get(url)
    if response.status_code == 200:
        data = response.json()
        return f"Thời tiết ở {city} là {data['current']['condition']['text']}."
    return "Dữ liệu thời tiết không khả dụng."

agent = Agent(
    name="WeatherAgent",
    instructions="Provide weather updates using the tool.",
    tools=[get_weather]
)
result = Runner.run_sync(agent, "What's the weather in Tokyo?")
print(result.final_output)  # Kết quả: "Thời tiết ở Tokyo là Nắng." (ví dụ)

Đăng ký một khóa API miễn phí tại weatherapi.com để thử nghiệm điều này.

Kết Hợp Nhiều Công Cụ

Các tác nhân có thể sử dụng nhiều công cụ đồng thời:

@function_tool
def log_entry(text: str) -> str:
    """Ghi lại một thông điệp."""
    return f"Đã ghi lại: {text}"

agent = Agent(
    name="MultiToolAgent",
    instructions="Use tools to search and log.",
    tools=[web_search, log_entry]
)
result = Runner.run_sync(agent, "Search for AI trends and log the query")
print(result.final_output)  # Kết quả bao gồm các kết quả tìm kiếm và xác nhận ghi lại

Chuyển Giao Tác Nhân

Chuyển giao cho phép các tác nhân phân công nhiệm vụ, cho phép các quy trình làm việc phức tạp.

Thiết Lập Chuyển Giao

Xác định một tác nhân chính với quyền truy cập vào các tác nhân phụ thông qua tham số handoffs:

from agents import Agent, Runner

english_agent = Agent(
    name="EnglishHelper",
    instructions="Respond in English only."
)
spanish_agent = Agent(
    name="SpanishHelper",
    instructions="Respond in Spanish only."
)
triage_agent = Agent(
    name="LanguageRouter",
    instructions="Detect the language and hand off to the appropriate agent.",
    handoffs=[english_agent, spanish_agent]
)

result = Runner.run_sync(triage_agent, "Hola, ¿qué tal?")
print(result.final_output)  # Kết quả: "¡Bien, gracias!" (hoặc tương tự)

Tác nhân triage_agent phân tích đầu vào và phân công cho tác nhân phù hợp theo ngôn ngữ.

Logic Chuyển Giao

Quyết định chuyển giao dựa vào các hướng dẫn của tác nhân chính. Ví dụ:

"Nếu đầu vào chứa các từ tiếng Tây Ban Nha, hãy chuyển giao cho SpanishHelper."
"Đối với đầu vào tiếng Anh, sử dụng EnglishHelper."

Kiểm tra với một đầu vào tiếng Anh:

result = Runner.run_sync(triage_agent, "How are you?")
print(result.final_output)  # Kết quả: "I'm good, thanks!"

Chuyển Giao Lồng Ghép

Đối với các quy trình làm việc sâu hơn, các tác nhân có thể chuyển giao cho các tác nhân khác với các sự chuyển giao:

analysis_agent = Agent(
    name="AnalysisBot",
    instructions="Analyze data and hand off for reporting."
)
report_agent = Agent(
    name="ReportBot",
    instructions="Generate a report from analysis."
)
main_agent = Agent(
    name="WorkflowManager",
    instructions="Start with analysis.",
    handoffs=[analysis_agent, report_agent]
)

result = Runner.run_sync(main_agent, "Analyze sales data")
print(result.final_output)  # Kết quả: Một báo cáo được tạo

Triển Khai Rào Chắn

Các rào chắn thực thi các ràng buộc trên các đầu vào và đầu ra bằng cách sử dụng các mô hình Pydantic.

Định Nghĩa Rào Chắn

Tạo một mô hình để xác thực cấu trúc đầu ra:

from pydantic import BaseModel
from agents import Agent, Runner

class QuestionCheck(BaseModel):
    is_question: bool
    reason: str

guard_agent = Agent(
    name="QuestionGuard",
    instructions="Determine if the input is a question.",
    output_type=QuestionCheck
)

result = Runner.run_sync(guard_agent, "What is the capital of France?")
print(result.final_output)  # Kết quả: {"is_question": true, "reason": "Kết thúc bằng dấu hỏi"}

Tích Hợp Quy Trình Làm Việc

Sử dụng các rào chắn để lọc các đầu vào:

task_agent = Agent(
    name="TaskProcessor",
    instructions="Process questions only.",
    handoffs=[guard_agent]
)
result = Runner.run_sync(task_agent, "Tell me a story")
print(result.final_output)  # Kết quả cho thấy đây không phải là một câu hỏi

Theo Dõi và Gỡ Lỗi

Theo dõi ghi lại chi tiết thực thi tác nhân, có thể truy cập qua OpenAI Dashboard.

Kích Hoạt Theo Dõi

Theo dõi là tự động. Mỗi lần chạy tạo một bản ghi với:

Dữ liệu đầu vào/đầu ra
Các cuộc gọi công cụ
Các sự kiện chuyển giao
Lỗi

Ví Dụ Gỡ Lỗi

Nếu một tác nhân gặp lỗi, xem lại bản ghi để xác định:

Các tham số công cụ không chính xác
Chuyển giao đi sai hướng
Lỗi API

Các Phương Pháp Tốt Nhất

Tối Ưu Hiệu Suất

Chọn Mô Hình: Sử dụng gpt-3.5-turbo cho tốc độ, gpt-4 cho lý luận phức tạp.
Nhiệt Độ: 0.2 cho độ chính xác, 0.9 cho tính sáng tạo.
Thực Thi Bất Đồng Bộ: Sử dụng Runner.run_async cho các nhiệm vụ song song.

Xử Lý Lỗi

Công Cụ: Trả về các thông điệp lỗi rõ ràng (ví dụ: "ID không hợp lệ").
Chuyển Giao: Bao gồm một tác nhân dự phòng cho các trường hợp lỗi.

Thiết Kế Quy Trình Làm Việc

Modularity: Chia nhỏ các nhiệm vụ giữa các tác nhân.
Rõ Ràng: Viết các hướng dẫn không mơ hồ.
Xác Thực: Áp dụng các rào chắn tại các giai đoạn quan trọng.

Kết Luận

OpenAI Agents SDK trao quyền cho các nhà phát triển xây dựng các hệ thống AI phức tạp với các tác nhân chuyên biệt, các công cụ tích hợp và các quy trình làm việc cộng tác. Hướng dẫn này cung cấp một nền tảng kỹ thuật để tận dụng tối đa tiềm năng của nó, hoàn chỉnh với các ví dụ và các phương pháp tốt nhất.

Vậy thì, điều gì sẽ xảy ra tiếp theo? Bắt đầu thử nghiệm! Chơi với các hướng dẫn, công cụ và quy trình làm việc khác nhau. Và nếu bạn gặp vấn đề, các công cụ như Apidog có thể giúp bạn kiểm tra API hãy tải xuống miễn phí.

button