AIFoundationAgent architecture

AI API fundamentals · OpenAI-compatible · Anthropic-native · 9router/OpenRouter notes

Chat Completions, Messages, Responses API: Bản đồ đầy đủ cho AI Agent

So sánh Chat Completions, Messages và Responses API để chọn đúng nền tảng khi xây dựng AI agent hiện đại.

Kết luận 80/20: Bắt đầu với Chat Completions nếu mới học; chuyển sang Messages khi dùng Claude nghiêm túc; học Responses sau khi nắm vững vòng lặp agent cơ bản.

Tóm tắt nhanh: khác nhau ở đâu?

Chat Completions API

Tư duy: trò chuyện tuyến tính, gửi mảng messages, nhận choices.
Tool: model trả tool_calls; ứng dụng tự thực thi tool rồi đưa kết quả về.
Phù hợp: chatbot đơn giản, proxy, học API.

Messages API

Tư duy: phân tách system, messages, và các content block.
Tool: vòng lặp tool_use → tool_result rõ ràng, dễ debug.
Phù hợp: Claude-native, khi cần kiểm soát chặt từng bước.

Responses API

Tư duy: một response là chuỗi các item: input, reasoning, tool call, output.
Tool: có thể dùng hosted tools do provider xử lý; custom tools vẫn cần app thực thi.
Phù hợp: agent hiện đại, multimodal, reasoning, workflow nhiều bước.

02 Mô hình tinh thần: API không phải là agent

Model API chỉ là “bộ não” suy luận: nhận ngữ cảnh, sinh quyết định/trả lời, trả kết quả có cấu trúc.

Để trở thành agent hoàn chỉnh cần lớp orchestration bên ngoài: memory, tool registry, planner, executor, verifier, retry, logging, permission, sandbox, budget control, và điều kiện dừng.

Một agent tối thiểu

1. User goal – người dùng đưa mục tiêu.
2. LLM decides – model quyết định trả lời ngay hoặc gọi tool.
3. App executes tools – code chạy search, database, shell, HTTP, browser, calculator.
4. Feed result back – kết quả tool đưa lại model để suy luận bước tiếp.

03 Chat Completions API

Chuẩn phổ thông nhất. Xem tương tác như một cuộc hội thoại; endpoint thường là POST /v1/chat/completions.

Điểm mạnh: dễ hiểu, nhiều SDK, chuyển model/provider nhanh.
Điểm yếu: agent phức tạp phải tự quản lý message, tool call, retry, state và nén context.

{
  "model": "openai/gpt-4.1-mini",
  "messages": [
    {"role": "system", "content": "Bạn là trợ lý hữu ích."},
    {"role": "user", "content": "Giải thích vector database đơn giản."}
  ],
  "temperature": 0.3
}

04 Messages API

Format native của Anthropic Claude. Có trường system riêng, messages chứa vai trò user/assistant, và nội dung là content block.

Điểm mạnh: tool use rõ ràng, hợp Claude và kiểm soát từng bước.
Điểm yếu: không phải mọi provider đều hỗ trợ native.

{
  "model": "anthropic/claude-sonnet-4-5",
  "max_tokens": 1024,
  "system": "Bạn là giáo viên kỹ thuật cẩn thận.",
  "messages": [
    {"role": "user", "content": "Giải thích API gateway trong AI app."}
  ]
}

05 Responses API

Hướng mới cho agent hiện đại. Gom nhiều năng lực vào mô hình input / output theo item.

Điểm mạnh: hợp agent dài hơi, reasoning, multimodal, trạng thái chuyển tiếp.
Lưu ý: custom function vẫn cần app thực thi và gửi kết quả về.

{
  "model": "openai/gpt-4.1-mini",
  "input": "Lập kế hoạch học AI agent trong 7 ngày.",
  "temperature": 0.2
}

06 Bảng so sánh sâu

Khía cạnh	Chat Completions	Messages	Responses
Mô hình dữ liệu	messages[] vào, choices[] ra	system riêng, messages[], blocks	input vào, output[] ra theo item
Provider gốc	OpenAI‑style, phổ biến trong gateway	Anthropic‑native	OpenAI‑style thế hệ mới
Dễ học	Dễ nhất cho newbie	Dễ nếu tập trung Claude	Mạnh nhưng nhiều khái niệm hơn
Tool calling	App tự loop qua tool_calls	App tự loop qua tool_use/tool_result	Hosted tools có thể do provider xử lý; custom tools vẫn cần app loop
Agent nhiều bước	Làm được nhưng phải tự thiết kế	Rõ ràng để kiểm soát từng bước Claude	Hợp nhất cho agent hiện đại nếu provider/model hỗ trợ tốt
Streaming	Token/event phổ biến	Event block rõ ràng	Output item/event linh hoạt hơn
Structured output	JSON mode/schema nếu provider hỗ trợ	Ép schema qua prompt/tool, tùy SDK	Hướng tốt hơn cho output có cấu trúc
Khi dùng 9router	/v1/chat/completions là mặc định	/v1/messages nếu provider hỗ trợ	/v1/responses có trong mapping nhưng cần kiểm tra model/provider

07 Trong AI Agent: chọn API theo kiến trúc nào?

Agent đơn giản

Nhiều tool cơ bản như search, calculator, tra cứu DB. Nên dùng: Chat Completions.

Agent Claude‑first

Cần Claude đọc file, gọi tool, sửa code, phản hồi có kiểm soát. Nên dùng: Messages API.

Agent platform dài hạn

Yêu cầu file, search, browser, reasoning, structured output, trạng thái liên tục. Nên dùng: Responses API nếu hỗ trợ ổn định.

while not done:
    1. Xây dựng context: system + user goal + memory + quan sát
    2. Gọi model API
    3. Nếu model trả lời cuối: dừng
    4. Nếu model yêu cầu tool:
        a. Xác thực quyền và tham số
        b. Thực thi tool trong môi trường sandbox
        c. Thu thập kết quả, lỗi, metadata
        d. Thêm kết quả tool vào context
    5. Kiểm tra ngân sách, giới hạn vòng lặp, an toàn, tiêu chí thành công

Sai lầm phổ biến

Cho model quyền gọi tool nguy hiểm mà không xác thực.
Không hạn chế số vòng lặp → agent chạy mãi.
Đưa toàn bộ lịch sử chat vào context => quá dài.
Lầm tưởng function calling nghĩa là model đã tự chạy function.
Không log input/output của tool → khó debug.

Thực hành tốt

Schema tool càng rõ thì agent càng ít gọi sai.
Luôn kiểm tra tham số trước khi chạy tool.
Tách planner, executor, verifier nếu task phức tạp.
Lưu observation ngắn gọn thay vì dump toàn bộ lịch sử.
Đặt điều kiện dừng rõ: thành công, thiếu dữ liệu, hết budget, cần người dùng quyết định.

08 Ghi chú riêng cho 9router trên máy này

Base URL mặc định: http://localhost:20128 (có thể ghi đè qua biến MITM_ROUTER_BASE).

API key được forward qua biến ROUTER_API_KEY.

/chat/completions → /v1/chat/completions

/v1/messages → /v1/messages

/responses → /v1/responses

9router chỉ là lớp định tuyến; tính năng thực tế phụ thuộc model, provider phía sau và mức tương thích của request body.

09 Ví dụ copy‑paste theo từng API

Các ví dụ curl được trích ngắn để dễ dùng trong bài học.

Chat Completions

curl -s http://localhost:20128/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTER_API_KEY" \
  -d '{"model":"openai/gpt-4.1-mini","messages":[{"role":"system","content":"Bạn là giáo viên AI API."},{"role":"user","content":"Giải thích embedding bằng ví dụ đời thường."}],"temperature":0.2}'

Messages

curl -s http://localhost:20128/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTER_API_KEY" \
  -d '{"model":"anthropic/claude-sonnet-4-5","max_tokens":1000,"system":"Bạn là giáo viên AI API, giải thích chậm và rõ.","messages":[{"role":"user","content":"Messages API khác Chat Completions thế nào?"}]}'

Responses

curl -s http://localhost:20128/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ROUTER_API_KEY" \
  -d '{"model":"openai/gpt-4.1-mini","input":"Tạo checklist thiết kế một AI agent đọc tài liệu nội bộ.","temperature":0.2}'

10 Cây quyết định thực dụng

Bạn mới học AI API? → Bắt đầu với Chat Completions.
Bạn build với Claude là chính? → Chuyển sang Messages API.
Bạn build agent platform lâu dài? → Xem xét Responses API.
Bạn dùng 9router/OpenRouter? → Bắt đầu từ /v1/chat/completions; chỉ chuyển endpoint khi đã xác nhận provider/model hỗ trợ.

11 Thuật ngữ cần nắm

Message

một lượt nói trong hội thoại, thường có role và content.

Content block

mảnh nội dung có type rõ ràng: text, image, tool_use, tool_result, …

Tool call

yêu cầu có cấu trúc từ model để app gọi một công cụ.

Hosted tool

tool do provider vận hành, ví dụ web search hoặc file search.

Custom function

function do app của bạn định nghĩa và thực thi trong backend.

Agent loop

vòng lặp: model quyết định → app chạy tool → model đọc kết quả → lặp lại cho đến khi xong.

Orchestration

lớp điều phối: context, tools, permissions, state, retries, verification, logging.

Structured output

ép model trả JSON/schema để backend xử lý an toàn hơn.

12 Nguồn tham khảo và giới hạn

Nguồn local: /home/akinet/.9router/runtime/mitm/server.js (mapping endpoint 9router trên máy này).
OpenAI API Reference: Chat Completions
OpenAI API Reference: Responses
Anthropic API Reference: Messages
Anthropic Docs: Tool use
OpenRouter Documentation

Lưu ý: Gateway như 9router hoặc OpenRouter có thể map request giữa nhiều provider. Vì vậy schema “được nhận” không luôn đồng nghĩa mọi tính năng provider-native đều hoạt động giống nhau trên mọi model.