API cho AI Agent - Hướng dẫn toàn diện cho người mới

Bạn đang xây dựng AI Agent và cảm thấy bối rối trước khái niệm API? Bạn không biết API là gì hay làm thế nào để sử dụng chúng? Đừng lo lắng, bạn không hề đơn độc! Rất nhiều người, kể cả những người không có nền tảng lập trình, cũng từng ở vị trí như bạn. Nhưng một khi đã hiểu và biết cách tận dụng API, bạn sẽ mở khóa một sức mạnh đáng kinh ngạc cho các AI Agent của mình.

Bài viết này sẽ giải thích về API một cách đơn giản nhất, không dùng thuật ngữ kỹ thuật phức tạp. Đến cuối bài, bạn sẽ tự tin thiết lập các lệnh gọi API (API call) trong quy trình làm việc (workflow) của AI Agent, đặc biệt là khi sử dụng công cụ n8n. Hãy cùng khám phá nhé!

API là gì? Tại sao lại quan trọng với AI Agent?

Nếu bạn đang xây dựng AI Agent trong một môi trường như n8n, về cơ bản, Agent của bạn chỉ có thể thực hiện các tác vụ trong phạm vi của môi trường đó. Nhưng nếu bạn muốn Agent tương tác với thế giới bên ngoài – ví dụ như gửi email qua Gmail, lấy dữ liệu từ Airtable, hay cập nhật thông tin lên HubSpot – bạn sẽ cần đến API.

API - Người trung gian Giao tiếp

API là viết tắt của Application Programming Interface (Giao diện Lập trình Ứng dụng). Hiểu một cách đơn giản nhất, API là một người trung gian cho phép hai hệ thống phần mềm khác nhau "nói chuyện" và trao đổi dữ liệu với nhau.

Để dễ hình dung, hãy tưởng tượng bạn đến một nhà hàng:

1. Bạn (Khách hàng): Bạn ngồi xuống, xem thực đơn (menu) và chọn món ăn.
2. Người phục vụ (API): Khi bạn sẵn sàng gọi món, bạn không trực tiếp vào bếp nói chuyện với đầu bếp. Thay vào đó, bạn gọi người phục vụ, nói cho họ biết bạn muốn món gì (ví dụ: "Tôi muốn một phần gà Parmesan").
3. Nhà bếp (Server/Hệ thống đích): Người phục vụ nhận yêu cầu của bạn và chuyển nó đến nhà bếp. Nhà bếp chuẩn bị đúng món bạn gọi (gà Parmesan, không phải cá hồi).
4. Phản hồi: Sau khi món ăn sẵn sàng, người phục vụ sẽ mang nó từ nhà bếp ra cho bạn.

Trong thế giới công nghệ:

• Bạn (hoặc AI Agent của bạn trong n8n): Muốn lấy hoặc gửi dữ liệu đến một dịch vụ khác.
• Thực đơn (API Documentation): Bạn cần xem "thực đơn" của dịch vụ đó, tức là tài liệu API (API Documentation), để biết họ cung cấp những "món ăn" (dữ liệu/chức năng) nào và cách "gọi món" (cách gửi yêu cầu).
• Người phục vụ (HTTP Request qua API): Bạn gửi một yêu cầu (HTTP Request) đến API của dịch vụ đó.
• Nhà bếp (Server của dịch vụ): Server nhận yêu cầu, xử lý và chuẩn bị dữ liệu bạn cần.
• Phản hồi (API Response): Server gửi lại dữ liệu cho bạn thông qua API.

Sức mạnh không giới hạn cho AI Agent

Khi bạn hiểu cách thiết lập bất kỳ lệnh gọi API nào, bạn sẽ mở ra khả năng gần như vô hạn cho các AI Agent của mình. Agent không còn bị giới hạn trong môi trường n8n mà có thể kết nối và tương tác với hàng ngàn dịch vụ và nguồn dữ liệu khác nhau trên internet. Đây chính là "game changer" giúp bạn xây dựng các hệ thống AI thực sự mạnh mẽ và linh hoạt.

Khi nào cần dùng HTTP Request API trong n8n? Native Integration và HTTP Request

Trong n8n, có hai cách chính để tương tác với các dịch vụ bên ngoài: Native Integration (Tích hợp gốc) và HTTP Request Node.

Native Integration: Sự tiện lợi được đóng gói sẵn

Khi bạn nhấn nút "+" trong n8n để thêm một node ứng dụng, bạn sẽ thấy một danh sách dài các dịch vụ được tích hợp sẵn như Airtable, Google Sheets, AWS, v.v. Đây chính là các Native Integration.

• Ưu điểm: Chúng có giao diện người dùng thân thiện, trực quan. Bạn chỉ cần điền thông tin vào các trường có sẵn mà không cần lo lắng về cấu trúc kỹ thuật của API call.
• Bản chất: Thực ra, mỗi Native Integration cũng chỉ là một HTTP Request được n8n "gói ghém" lại cho dễ sử dụng.

HTTP Request Node: Tự do tùy chỉnh không giới hạn

Vậy khi nào bạn cần dùng đến HTTP Request Node?

• Khi dịch vụ bạn muốn kết nối không có Native Integration trong n8n.
• Khi bạn cần những tùy chỉnh nâng cao mà Native Integration không hỗ trợ.

Ví dụ với OpenWeatherMap:

Giả sử bạn muốn lấy dữ liệu thời tiết.

• Cách 1 (Native Integration): n8n có node OpenWeatherMap. Bạn chỉ cần nhập Vĩ độ (Latitude) và Kinh độ (Longitude), chọn định dạng (Imperial/Metric), và bạn sẽ nhận được dữ liệu thời tiết. Rất đơn giản!
• Cách 2 (HTTP Request Node): Bạn cũng có thể dùng HTTP Request Node để gọi trực tiếp đến API của OpenWeatherMap. Bạn sẽ phải tự điền URL endpoint, các tham số như lat, lon. Kết quả nhận được vẫn là dữ liệu thời tiết tương tự.

Cách thứ hai trông có vẻ "đáng sợ" và phức tạp hơn ban đầu, nhưng nó cho bạn thấy bản chất của việc tương tác API. Một khi bạn hiểu cách thiết lập HTTP Request, bạn có thể kết nối với bất kỳ dịch vụ nào có API, dù n8n có hỗ trợ sẵn hay không.

Giải phẫu một HTTP Request: 5 Yếu tố then chốt

Khi bạn thiết lập một HTTP Request, về cơ bản bạn đang "lọc" và "chọn lựa" thông tin mình muốn từ một server. Giống như khi đặt pizza, bạn phải chọn cửa hàng, rồi chọn loại pizza (cỡ, topping,...).

Có 5 thành phần chính bạn cần quan tâm khi đọc tài liệu API và thiết lập HTTP Request:

1. Method (Phương thức)

Đây là hành động bạn muốn thực hiện với API. Hai phương thức phổ biến nhất là:

• GET: Dùng để lấy dữ liệu từ server. Bạn thường không gửi nhiều thông tin kèm theo, chỉ yêu cầu server trả về dữ liệu.
• POST: Dùng để gửi dữ liệu lên server để server xử lý, tạo mới, hoặc cập nhật. Sau đó server có thể trả về kết quả.

Tài liệu API (API documentation) sẽ luôn chỉ rõ bạn cần dùng phương thức nào (GET, POST, PUT, DELETE, v.v.).

2. Endpoint (URL)

Đây là địa chỉ (URL) cụ thể của tài nguyên hoặc chức năng trên server mà bạn muốn tương tác. Ví dụ, endpoint để tìm kiếm trên Google có thể là https://www.google.com/search.

3. Query Parameters (Tham số Truy vấn)

Thường được sử dụng với phương thức GET để lọc hoặc chỉ định rõ hơn dữ liệu bạn muốn. Chúng xuất hiện sau dấu ? trong URL và được phân tách bằng dấu &.

• Ví dụ: https://api.example.com/data?category=electronics&limit=10
  • category=electronics: Lấy dữ liệu thuộc danh mục "electronics".
  • limit=10: Giới hạn 10 kết quả.
• Khi bạn tìm kiếm "pizza" trên Google, URL có thể là google.com/search?q=pizza. Ở đây, q=pizza là một query parameter.

4. Header Parameters (Tham số Tiêu đề)

Chứa thông tin bổ sung về bản thân request, không phải là dữ liệu chính bạn gửi đi. Một trong những header quan trọng nhất là Authorization (Xác thực).

• API Key: Nhiều API yêu cầu bạn cung cấp một API Key (khóa API) để xác thực quyền truy cập. Đây giống như "mật khẩu" của bạn cho dịch vụ đó, và bạn cần giữ nó bí mật. Nếu API Key bị lộ, người khác có thể sử dụng nó và tiêu tốn tài nguyên (ví dụ: tiền trong tài khoản API) của bạn.
• Cách gửi API Key:
  • Thường là: Authorization: Bearer YOUR_API_KEY (chú ý chữ "Bearer" và dấu cách)
  • Hoặc: X-API-Key: YOUR_API_KEY (tên header có thể khác nhau)
• Tài liệu API sẽ hướng dẫn chi tiết cách thiết lập header xác thực.

5. Body Parameters (Tham số Thân)

Đây là nơi chứa dữ liệu chính bạn muốn gửi đến server, đặc biệt quan trọng với các phương thức như POST, PUT, PATCH. Dữ liệu này thường được định dạng dưới dạng JSON (JavaScript Object Notation).

• Ví dụ: Nếu bạn muốn tạo một người dùng mới trong CRM, bạn có thể gửi một body request như sau:

  {
    "name": "John Doe",
    "email": "[email protected]"
  }
  

• Server sẽ nhận dữ liệu này, tạo người dùng mới, và có thể trả về thông tin của người dùng vừa tạo.

Tóm lại, tài liệu API sẽ là kim chỉ nam cho bạn. Nó sẽ cho bạn biết cần dùng method nào, endpoint là gì, và cách cấu hình các query, header, body parameters.

Sức mạnh của cURL Command: Sao chép và Dán!

Tin vui cho chúng ta là nhiều tài liệu API hiện đại cung cấp một thứ gọi là cURL command. Đây là một dòng lệnh đơn giản mà bạn có thể sao chép, chứa đựng toàn bộ thông tin cấu hình của một API request (method, endpoint, headers, body).

Nhiều công cụ, bao gồm cả n8n, cho phép bạn Import cURL. Bạn chỉ cần dán cURL command vào, và công cụ sẽ tự động điền các trường tương ứng trong giao diện thiết lập HTTP request. Việc của bạn sau đó thường chỉ là thay thế API key của mình và điều chỉnh một vài thông số nếu cần.

Ví dụ với cURL của Tavi API (một dịch vụ tìm kiếm):

curl -X POST https://api.tavily.com/search \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "api_key": "YOUR_API_TOKEN", # Có thể nằm trong body hoặc header tùy API
        "query": "Who is Leo Messi?",
        "search_depth": "basic",
        "include_answer": false,
        "include_images": false,
        "include_raw_content": false,
        "max_results": 5,
        "topic": "general"
      }'

Từ cURL này, bạn có thể thấy:

• Method: POST
• Endpoint: https://api.tavily.com/search
• Header: Authorization: Bearer YOUR_API_TOKEN và Content-Type: application/json
• Body (phần -d): Là một đối tượng JSON chứa query, search_depth, v.v. Đây chính là các "bộ lọc" bạn đặt ra.

Về JSON: Đừng để JSON làm bạn sợ hãi. Nó chỉ là một cách định dạng dữ liệu dưới dạng cặp key: value (khóa: giá trị), rất dễ đọc và sử dụng. Bạn sẽ gửi body parameters dưới dạng JSON và cũng thường nhận lại dữ liệu từ API dưới dạng JSON.

Thực hành: Kết nối Perplexity API với AI Agent trong n8n

Bây giờ, chúng ta sẽ cùng thực hành kết nối với Perplexity API (một công cụ tìm kiếm và nghiên cứu AI mạnh mẽ) bằng HTTP Request Node trong n8n.

Bước 1: Kiểm tra Native Integration

Đầu tiên, trong n8n, thử tìm node "Perplexity". Nếu không có, điều đó có nghĩa là chúng ta cần dùng HTTP Request Node.

Bước 2: Tìm API Documentation

Lên Google và tìm kiếm "Perplexity API documentation". Truy cập vào trang tài liệu chính thức.

Bước 3: Lấy cURL Command

Trong tài liệu API của Perplexity, tìm đến mục API Reference hoặc tương tự. Họ thường cung cấp ví dụ request dưới dạng cURL. Hãy đảm bảo bạn đang xem tab "cURL" (không phải Python hay ngôn ngữ khác) và sao chép (copy) toàn bộ cURL command đó.

Bước 4: Import cURL vào n8n

1. Trong workflow n8n của bạn, thêm một node "HTTP Request".
2. Mở cài đặt của node này, bạn sẽ thấy nút "Import cURL".
3. Nhấp vào đó và dán (paste) cURL command bạn vừa copy từ tài liệu Perplexity. Nhấn Import.

N8n sẽ tự động điền các thông tin sau cho bạn:

• Method: (ví dụ: POST)
• URL (Endpoint): (ví dụ: https://api.perplexity.ai/chat/completions)
• Headers: Sẽ có mục Authorization, thường là Bearer YOUR_PERPLEXITY_API_KEY hoặc tương tự.
• Body (JSON): Cấu trúc JSON với các trường như model, messages.

Bước 5: Cấu hình Authentication (API Key)

1. Quay lại trang Perplexity, vào phần tài khoản (Account) -> Settings (Cài đặt) -> API Keys.
2. Tạo hoặc sao chép một API Key của bạn.
3. Trong node HTTP Request của n8n, tìm đến phần Headers.
4. Tìm dòng Authorization. Giá trị của nó sẽ là Bearer YOUR_PERPLEXITY_API_KEY (hoặc một placeholder tương tự).
5. Xóa YOUR_PERPLEXITY_API_KEY và dán API Key thực của bạn vào đó. Lưu ý: Giữ nguyên chữ Bearer và dấu cách sau nó.

Bước 6: Kiểm tra và Tùy chỉnh Body Request

1. Nhấn nút "Test Step" trong n8n để xem request có hoạt động không. Nếu thành công, bạn sẽ thấy dữ liệu trả về từ Perplexity.

2. Xem lại tài liệu API của Perplexity để hiểu các tham số trong Body:

   • model (bắt buộc): Chọn model Perplexity bạn muốn dùng.
   • messages (bắt buộc): Một mảng các tin nhắn, thường bao gồm:
     • role: "system": Nội dung hướng dẫn AI cách trả lời (ví dụ: "Be precise and concise." - Hãy chính xác và súc tích).
     • role: "user": Câu hỏi hoặc yêu cầu thực tế của bạn (ví dụ: "How many stars are there in our galaxy?").
   • Các tham số tùy chọn: max_tokens (số lượng token tối đa), temperature (độ ngẫu nhiên của câu trả lời, từ 0 đến 2), frequency_penalty, v.v. Tài liệu sẽ ghi rõ ý nghĩa, kiểu dữ liệu (number, string, boolean), giá trị mặc định và các giá trị được chấp nhận.

   Thử nghiệm:

   • Thay đổi nội dung system message, ví dụ: "Be funny in your answer."
   • Thay đổi nội dung user message, ví dụ: "How long do cows live?"
   • Nhấn "Test Step" để xem kết quả thay đổi như thế nào.

Bước 7: Tạo Tool API động cho AI Agent

Bây giờ, chúng ta muốn AI Agent của mình có thể tự sử dụng Perplexity để tìm kiếm thông tin dựa trên yêu cầu của người dùng, chứ không phải một câu hỏi cố định.

1. Trong n8n, nếu bạn đang xây dựng một AI Agent, hãy thêm một "Tool" mới cho Agent đó. Chọn loại Tool là "HTTP Request".
2. Import cURL và Cấu hình Authentication tiện lợi:
   • Lặp lại việc import cURL của Perplexity như trên.
   • Thay vì điền API Key trực tiếp vào Header mỗi lần, hãy sử dụng tính năng "Authentication" của node.
   • Nhấp vào tab "Authentication", chọn "Generic Credential Type".
   • Chọn "Header Auth".
   • Nhấn "Create New Credential".
     • Name: Authorization (viết hoa chữ A)
     • Value: Bearer YOUR_PERPLEXITY_API_KEY (dán API key của bạn vào)
   • Đặt tên cho credential này (ví dụ: "Perplexity API Key") và lưu lại.
   • Sau khi thiết lập xong, quay lại tab "Main" của node HTTP Request, bạn có thể tắt (turn off) phần Headers đi, vì authentication đã được xử lý ở tab "Authentication".
3. Làm động Body Request:
   • Trong phần Body (JSON) của node HTTP Request, tìm đến nội dung của user message.
   • Thay đổi trường content từ một chuỗi cố định thành một biểu thức (expression) để n8n có thể điền giá trị động vào đó.
   • Chuyển chế độ của Body thành "Expression".
   • Sửa giá trị của content trong user message thành: {{$fromAI("search_term")}}
     • {{ ... }}: Ký hiệu biểu thức trong n8n.
     • $fromAI("search_term"): Đây là một hàm đặc biệt báo cho AI Agent biết rằng nó cần cung cấp một giá trị cho biến search_term tại đây, dựa trên yêu cầu của người dùng.
4. Đặt tên Tool: Đặt tên cho Tool này một cách trực quan để AI Agent hiểu (ví dụ: web_search_perplexity).
5. Kiểm tra với AI Agent:
   • Chạy AI Agent và yêu cầu nó tìm kiếm một thông tin nào đó, ví dụ: "What are the best movies to watch this year?"
   • Kiểm tra log của node HTTP Request Tool. Bạn sẽ thấy trong phần Body gửi đi, trường content của user message đã được AI Agent thay thế bằng "What are the best movies to watch this year?" (hoặc một truy vấn tương tự).

Giải mã các Mã Trạng thái (Status Codes) API thường gặp

Khi bạn gửi một HTTP Request, server sẽ trả về một mã trạng thái (status code) cho biết kết quả của request đó. Hiểu các mã này rất quan trọng để gỡ lỗi:

• 2xx (Ví dụ: 200 OK) - Thành công: Request của bạn đã được xử lý thành công. Nếu bạn yêu cầu dữ liệu, nó sẽ nằm trong phần phản hồi. Đôi khi bạn không thấy rõ mã 200 nhưng nếu nhận được dữ liệu mong muốn thì mọi thứ đều ổn.

• 4xx (Lỗi từ Client - Phía bạn): Có lỗi trong cách bạn thiết lập request.

  • 400 Bad Request: Request của bạn có cú pháp không hợp lệ.
    • Nguyên nhân phổ biến: JSON trong body không đúng (ví dụ: thừa/thiếu dấu ngoặc kép, dấu phẩy, hoặc sai cấu trúc).
    • Mẹo gỡ lỗi: Copy phần JSON bạn gửi đi, dán vào một công cụ kiểm tra JSON online hoặc hỏi ChatGPT: "JSON này có lỗi gì không?".
  • 401 Unauthorized: Bạn chưa được xác thực.
    • Nguyên nhân phổ biến: API Key sai, thiếu API Key, hoặc định dạng Authorization header không đúng.
  • 403 Forbidden: Bạn đã được xác thực (API Key đúng) nhưng không có quyền truy cập tài nguyên hoặc thực hiện hành động đó. Có thể gói API của bạn không hỗ trợ tính năng này.
  • 404 Not Found: Endpoint (URL) bạn đang gọi không tồn tại trên server. Kiểm tra lại URL xem có gõ nhầm không.
  • 429 Too Many Requests: Bạn đã gửi quá nhiều request trong một khoảng thời gian ngắn và bị giới hạn.

• 5xx (Lỗi từ Server - Phía dịch vụ API): Có lỗi xảy ra ở phía server cung cấp API, không phải lỗi của bạn.

  • Nguyên nhân: Server bị lỗi, quá tải, đang bảo trì, v.v.
  • Tin tốt: Đây không phải lỗi do bạn cấu hình sai. Bạn có thể thử lại sau hoặc kiểm tra trang trạng thái của dịch vụ API đó.

Luôn đọc tài liệu API! Hầu hết các tài liệu API tốt đều có một mục liệt kê các mã trạng thái có thể trả về và ý nghĩa của chúng, giúp bạn gỡ lỗi dễ dàng hơn. Quan trọng nhất là đọc kỹ thông báo lỗi mà API trả về, nó thường chứa gợi ý về vấn đề.

Hy vọng bài viết này đã giúp bạn cảm thấy thoải mái hơn khi tìm hiểu và làm việc với API, đặc biệt là API cho AI Agent. Hãy nhớ rằng:

• API không quá đáng sợ: Về cơ bản, bạn chỉ đang thiết lập các "bộ lọc" và "cần gạt" để yêu cầu dữ liệu hoặc hành động từ một hệ thống khác. Nó giống như việc bạn đặt hàng online vậy.
• Đọc tài liệu API là chìa khóa: Mỗi API có quy tắc riêng. Tài liệu là người bạn tốt nhất của bạn.
• Thực hành, thực hành, thực hành: Cách tốt nhất để thành thạo là bắt tay vào làm. Hãy thử kết nối với các API khác nhau.
• Sử dụng cURL command: Nó giúp bạn tiết kiệm rất nhiều thời gian khi bắt đầu.
• Hiểu các mã lỗi: Điều này giúp bạn nhanh chóng xác định và khắc phục sự cố.

Việc hiểu và sử dụng API sẽ thực sự nâng tầm các AI Agent bạn xây dựng, cho phép chúng tương tác, thu thập thông tin và tự động hóa các tác vụ phức tạp hơn rất nhiều. Chúc bạn thành công trên hành trình khám phá sức mạnh của API!