Giới thiệu

Các agent AI trở nên hữu ích khi chúng có thể giao tiếp với thế giới bên ngoài. REST API là cách phổ biến nhất để các hệ thống exposing chức năng, vì vậy agent phải có thể gọi chúng theo thời điểm cần thiết. Thách thức là hầu hết API được thiết kế cho các khách hàng do con người điều khiển (bảng điều khiển, ứng dụng di động), không phải cho các người ra quyết định tự động. Trước khi một agent có thể sử dụng API, bạn cần dịch hợp đồng API thành một thứ mà agent có thể hiểu và gọi.

Đóng gói một API như một Công cụ

Một công cụ, từ góc nhìn của agent, là một hàm có tên, mô tả và một tập tham số. Bạn xây dựng một lớp wrapper mỏng nhận đầu vào có cấu trúc từ agent (ví dụ, tên thành phố) và trả về kết quả có cấu trúc.

import requests

def get_weather(city: str) -> dict:
    url = "https://api.example.com/weather"
    params = {"q": city, "units": "metric"}
    response = requests.get(url, params=params, timeout=10)
    response.raise_for_status()
    return response.json()

Lớp wrapper che giấu các chi tiết HTTP (headers, mã trạng thái, phân tích JSON) và露 một chữ ký hàm sạch. Agent chỉ thấy tên hàm, docstring hoặc mô tả của nó, và các tham số được gõ.

Cấu trúc mô tả cho Agent

Mô tả là thứ cho agent biết khi nào và làm thế nào để gọi công cụ. Một mô tả công cụ tốt có ba phần: một tóm tắt ngắn gọn về những gì công cụ làm, một ghi chú về khi nào nên sử dụng (và quan trọng như vậy, khi nào không nên), và mô tả cho từng tham số gồm định dạng và giới hạn.

{
  "name": "get_weather",
  "description": "Get current weather for a city. Use when the user asks about weather, temperature, or conditions outdoors. Do not use for forecasts beyond 24 hours.",
  "parameters": {
    "city": {
      "type": "string",
      "description": "City name in English, e.g. 'Hanoi' or 'Tokyo'"
    }
  }
}

Giữ cho mô tả trung thực. Tránh từ ngữ quảng cáo như "mạnh mẽ" hay "nâng cao" — agent đưa ra quyết định gọi dựa trên tiện ích, không dựa trên ngôn ngữ Marketing.

Xử lý giới hạn tần suất, phân trang và lỗi

APIs thất bại theo cách có thể dự đoán trước. Wrapper của bạn phải xử lý những lỗi đó để tác nhân nhận được phản hồi hữu ích thay vì các stack traces thô.

Đối với giới hạn tần suất, tôn trọng header Retry-After khi có và back off tăng dần theo cấp số mũ trên các phản hồi 429 lặp lại. Bao quanh cuộc gọi trong vòng lặp retry với một số lần thử tối đa để tránh chờ vô hạn.

import time
import requests

def call_with_retry(url, params, max_attempts=3):
    for attempt in range(max_attempts):
        response = requests.get(url, params=params, timeout=10)
        if response.status_code == 429:
            wait = int(response.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue
        response.raise_for_status()
        return response.json()
    raise Exception("Rate limited after retries")

Đối với phân trang, thiết kế wrapper sao cho nó chấp nhận tham số trang hoặc cursor và trả về tín hiệu rõ ràng khi còn có trang tiếp theo. Để tác nhân quyết định có tiếp tục lấy thêm hay không — nó có thể suy luận về chi phí và liên quan tốt hơn một vòng lặp được cố định.

Đối với lỗi, trả về một đối tượng có cấu trúc thay vì ném ngoại lệ một cách mù quáng. Bao gồm mã trạng thái, một lý do ngắn gọn có thể đọc được bởi người, và gợi ý cách khắc phục tùy chọn. Điều này cho phép tác nhân retry với tham số đã sửa, chuyển công cụ, hoặc báo sự cố lại cho người dùng.

Tóm tắt

Hãy xem mỗi API như một công cụ với ba lớp: một chữ ký hàm sạch, một mô tả chính xác mà tác nhân có thể dùng để lựa chọn, và một wrapper mạnh mẽ xử lý thực tế rối ren của HTTP — retries, phân trang và báo cáo lỗi. Wrapper là hợp đồng giữa một dịch vụ bên ngoài dễ hỏng và một tác nhân lý luận cần đầu vào có thể dự đoán để đưa ra quyết định tốt.

Những sai lầm phổ biến

Wrap một API mà không có mô tả cho biết khi nào không nên dùng. Để nguyên các ngoại lệ thô tràn lên tác nhân thay vì trả về các đối tượng lỗi có cấu trúc. Cố định vòng lặp phân trang khiến tác nhân không thể bỏ qua trang hoặc dừng sớm. Bỏ qua header Retry-After và dùng độ trễ cố định khiến bạn bị chặn nhanh hơn.