Sebastian Petrus

Posted on Jul 6 • Originally published at apidog.com

agentHints: Dạy CLIs giao tiếp với Agents

Đây là chuỗi 10 phần chia sẻ cách Apidog đã phát triển Apidog CLI, một công cụ dòng lệnh để kiểm thử API và quản lý vòng đời API. Bạn có thể đọc theo thứ tự hoặc chuyển đến phần phù hợp với vấn đề đang xử lý.

Dùng thử Apidog hôm nay

Phần	Tiêu đề	Trọng tâm
1	Chúng tôi đã xây dựng 126 công cụ MCP. Nhưng đó không phải là giải pháp tốt nhất cho Agent	Khám phá vấn đề
2	Tại sao chúng tôi phát triển Apidog CLI hoàn toàn mới	Phát triển kiến trúc
3	Quy tắc vàng: CLI tạo ra sự thật, Mô hình hành động dựa trên sự thật	Triết lý cốt lõi
4	`agentHints`: Dạy CLI giao tiếp với Agent	Đầu ra có cấu trúc
5	KỸ NĂNG: Vận chuyển kinh nghiệm vận hành dưới dạng Mã	Kinh nghiệm vận hành
6	Các con số không nói dối: Giảm 30% cuộc gọi công cụ, giảm 25% token	Kết quả định lượng
7	Từ PRD đến vòng lặp kiểm thử: Một quy trình làm việc Agent hoàn chỉnh với Apidog CLI	Hướng dẫn thực hành
8	Tại sao khả năng tương thích CI/CD là không thể thiếu đối với các công cụ Agent	Quan điểm DevOps
9	Nhánh AI: Thay đổi dự án an toàn hơn với AI Agent	Lớp bảo mật
10	Spec-First đã là quá khứ. Chào mừng đến với Skill-First.	Tầm nhìn & tương lai

Đầu ra CLI truyền thống dành cho con người. Agent cần kết quả có cấu trúc, lý do lỗi và gợi ý bước tiếp theo. agentHints biến kinh nghiệm sản phẩm thành hướng dẫn có thể đọc bằng máy.

Khoảng cách trong đầu ra CLI

Đầu ra CLI truyền thống thường được thiết kế cho con người:

Thành công	Thất bại
In `"Thành công"` hoặc `"Hoàn tất"`	In thông báo lỗi
Có thể hiển thị tài nguyên đã tạo	Có thể hiển thị stack trace
Con người đọc và quyết định bước tiếp theo	Con người đọc và gỡ lỗi

Cách này hoạt động tốt khi người dùng là developer. Developer có thể:

Diễn giải thông báo mơ hồ
Quyết định bước tiếp theo
Ghi nhớ ngữ cảnh từ các lệnh trước
Áp dụng kinh nghiệm để sửa lỗi hoặc tiếp tục

Nhưng AI Agent không vận hành như vậy.

Agent không chỉ cần biết lệnh đã thành công hay thất bại. Chúng cần biết:

Kết quả thực tế là gì
Có thể parse kết quả bằng code hay không
Nếu lỗi, lỗi thuộc loại nào
Bước tiếp theo nên làm gì

Những gì Agent thực sự cần

Agent cần kết nối kết quả của một lệnh với chuỗi hành động tiếp theo.

Nhu cầu của Agent	Lý do
Kết quả có cấu trúc	Agent phải parse đầu ra bằng lập trình
Lý do thất bại rõ ràng	Agent cần chi tiết cụ thể, không phải thông báo chung chung
Gợi ý bước tiếp theo	Agent cần hướng dẫn để tiếp tục đúng quy trình

Ví dụ, khi CLI trả về:

Test case created successfully.

Developer có thể hiểu rằng nên kiểm tra lại test case, thêm assertion, đưa test case vào scenario, rồi chạy thử.

Agent thì không chắc chắn. Nếu không có chỉ dẫn, nó có thể tiếp tục tạo tài nguyên tiếp theo dựa trên giả định.

`agentHints`: Cấu trúc đầu ra cho Agent

Apidog CLI thêm agentHints vào đầu ra JSON để Agent có thể đọc, parse và hành động.

Ví dụ phản hồi sau khi tạo test case:

{
  "success": true,
  "data": {
    "id": "12345",
    "name": "Health Check Test Case"
  },
  "agentHints": {
    "summary": "Test case created successfully.",
    "nextSteps": [
      "Read the created test case back to confirm structure.",
      "Add assertions if the test case needs response validation.",
      "Add the test case to a test scenario for integration testing.",
      "Run related tests after adding to scenario."
    ]
  }
}

Cấu trúc này có ba phần chính:

Thành phần	Mục đích
`success` + `data`	Kết quả thực tế của lệnh
`agentHints.summary`	Tóm tắt ngắn gọn cho con người hoặc log
`agentHints.nextSteps`	Danh sách bước tiếp theo để Agent xử lý

Với cấu trúc này, Agent không cần đoán. Nó có thể lấy agentHints.nextSteps[0] và tiếp tục theo quy trình được đề xuất.

Vấn đề: quán tính thực thi

Một hành vi phổ biến của Agent là tiếp tục ghi dữ liệu ngay sau khi nhận được kết quả thành công.

Ví dụ:

Agent: Tạo test case
CLI: Trả về thành công
Agent: Tạo test scenario ngay lập tức, không đọc lại test case
Agent: Chạy test ngay lập tức
Kết quả: Scenario có cấu trúc sai, test thất bại

Trong các quy trình API phức tạp, cách làm này không an toàn. Một workflow tốt hơn là:

Tạo tài nguyên
Đọc lại tài nguyên vừa tạo
Xác nhận cấu trúc thực tế
Chỉ tiếp tục khi dữ liệu đã đúng

Tại sao bước đọc lại quan trọng

Bỏ qua bước đọc lại có thể gây lỗi thực tế trong workflow.

Vấn đề	Nguyên nhân
Giá trị mặc định sai	Server có thể tự điền default value mà Agent không biết
Thiếu ID liên quan	Import hoặc create có thể sinh ID nội bộ mới
Biến thể cấu trúc	UI hoặc backend có thể lưu dữ liệu theo format cụ thể
Giả định không chính xác	Agent tiếp tục hành động dựa trên dữ liệu tưởng tượng

Nếu Agent không đọc lại cấu trúc thực tế, nó có thể tiếp tục ghi dữ liệu dựa trên phỏng đoán thay vì trạng thái thật của hệ thống.

Cách `agentHints` điều hướng Agent

agentHints đặt hướng dẫn ngay tại thời điểm Agent cần ra quyết định.

Ví dụ sau khi tạo test case:

{
  "agentHints": {
    "nextSteps": [
      "Read back the created test case with --with-case-detail flag.",
      "Validate any updates with cli-schema before writing.",
      "Run tests after completing test scenario."
    ]
  }
}

Một Agent có thể xử lý đầu ra theo luồng sau:

1. Nhận JSON từ CLI
2. Parse field agentHints
3. Lấy nextSteps[0]
4. Thực hiện bước đọc lại test case
5. Dùng dữ liệu thực tế cho bước tiếp theo

Ví dụ pseudo-code:

const result = await runCliCommand("apidog test-case create ...");

if (result.success && result.agentHints?.nextSteps?.length) {
  const nextStep = result.agentHints.nextSteps[0];

  if (nextStep.includes("Read back")) {
    await runCliCommand("apidog test-case get 12345 --with-case-detail");
  }
}

Điểm quan trọng không phải là Agent phải hard-code mọi câu lệnh. Điểm quan trọng là CLI trả về tín hiệu đủ rõ để Agent biết nên dừng, đọc lại, xác thực hoặc tiếp tục.

Vai trò mới của CLI trong workflow Agent

agentHints thay đổi vai trò của CLI.

Vai trò cũ	Vai trò mới
Bộ thực thi lệnh	Bộ điều hướng workflow
In kết quả	Đề xuất bước tiếp theo
Đầu ra dễ đọc cho con người	Cấu trúc dễ đọc cho Agent
Phản hồi một lần	Hướng dẫn liên tục qua từng bước

CLI không chỉ chạy lệnh và kết thúc. Nó trở thành một bộ điều hướng trạng thái nhẹ cho Agent.

Cây workflow tích hợp

Apidog CLI tích hợp nhiều workflow dạng cây để đưa ra gợi ý theo ngữ cảnh.

Các gợi ý này không chỉ là thông báo tĩnh. Chúng phụ thuộc vào thao tác, loại tài nguyên và trạng thái thành công/thất bại.

Tính năng	Mô tả
Nhận biết ngữ cảnh	Gợi ý khớp với thao tác cụ thể
Theo loại tài nguyên	Endpoint, test case, scenario có gợi ý khác nhau
Nhận biết workflow	Gợi ý phản ánh chuỗi thao tác thường gặp
Có thông tin lỗi	Thành công và thất bại trả về gợi ý khác nhau

Ví dụ sau khi cập nhật test scenario thành công:

{
  "agentHints": {
    "summary": "Test scenario updated successfully.",
    "nextSteps": [
      "Run the test scenario to verify changes.",
      "Check the test report for any failures.",
      "If failures occur, read back scenario steps for debugging."
    ]
  }
}

Ví dụ khi xác thực thất bại:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'comparator' has invalid value",
    "details": []
  },
  "agentHints": {
    "summary": "Validation failed. Fix the errors and re-validate.",
    "nextSteps": [
      "Review the error details in the output.",
      "Adjust the JSON file based on error suggestions.",
      "Re-run cli-schema validate before writing."
    ]
  }
}

Lỗi không chỉ được báo cáo. Lỗi trở thành một phần của workflow có thể hành động.

Vòng lặp an toàn hơn với `agentHints`

Một workflow có agentHints có thể trông như sau:

Bước 1: Agent tạo test case
        ↓
Đầu ra CLI: success + agentHints
        ↓
agentHints.nextSteps[0]: "Đọc lại test case đã tạo"
        ↓
Bước 2: Agent đọc lại test case với cấu trúc thực tế
        ↓
Đầu ra CLI: dữ liệu test case + agentHints
        ↓
agentHints.nextSteps[0]: "Thêm assertion nếu cần"
        ↓
Bước 3: Agent thêm assertion dựa trên cấu trúc thực tế
        ↓
Đầu ra CLI: success + agentHints
        ↓
agentHints.nextSteps[0]: "Chạy kiểm thử"
        ↓
Bước 4: Agent chạy test
        ↓
Đầu ra CLI: báo cáo kiểm thử

Workflow này có hai đặc điểm quan trọng:

Agent không nhảy mù từ bước tạo sang bước chạy test
Mỗi bước đều dựa trên dữ liệu thực tế từ CLI

So sánh: có và không có `agentHints`

Kịch bản	Không có `agentHints`	Với `agentHints`
Sau khi tạo tài nguyên	Agent tiếp tục ghi bước tiếp theo	Agent đọc lại trước
Sau khi cập nhật	Agent giả định dữ liệu đúng	Agent xác minh cấu trúc
Sau khi validate thành công	Agent ghi ngay lập tức	Agent ghi rồi đọc lại
Sau khi validate thất bại	Agent không rõ nên sửa gì	Agent nhận gợi ý sửa lỗi cụ thể
Sau khi chạy test	Agent chỉ thấy pass/fail	Agent nhận hướng dẫn debug tiếp theo

Cách áp dụng pattern này cho CLI của bạn

Nếu bạn đang xây dựng CLI cho AI Agent, có thể áp dụng pattern tương tự:

1. Luôn trả về JSON có cấu trúc

{
  "success": true,
  "data": {},
  "agentHints": {}
}

2. Tách dữ liệu thực tế khỏi hướng dẫn

Không trộn message dành cho người dùng với dữ liệu máy cần parse.

{
  "data": {
    "id": "12345"
  },
  "agentHints": {
    "summary": "Resource created.",
    "nextSteps": [
      "Read back the resource before updating related entities."
    ]
  }
}

3. Với lỗi, trả về mã lỗi và bước khắc phục

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": []
  },
  "agentHints": {
    "nextSteps": [
      "Inspect error.details.",
      "Fix the request body.",
      "Run validation again before submitting."
    ]
  }
}

4. Ưu tiên bước xác minh sau thao tác ghi

Sau các lệnh create, update, import, Agent nên được nhắc đọc lại hoặc validate trước khi tiếp tục.

Tiếp theo là gì

Khi CLI đã có thể hướng dẫn Agent qua từng bước, câu hỏi tiếp theo là:

Làm thế nào để Agent biết workflow nào cần tuân theo ngay từ đầu?

Trong Phần 5, KỸ NĂNG: Vận chuyển kinh nghiệm vận hành dưới dạng Mã, chúng ta sẽ tìm hiểu cách SKILL đóng gói kiến thức vận hành: khi nào dùng lệnh nào, thứ tự thực hiện ra sao và trường nào không nên để Agent tự đoán.

Những điểm chính

Đầu ra CLI truyền thống phục vụ con người; Agent cần cấu trúc rõ ràng hơn
agentHints bổ sung summary và nextSteps vào đầu ra JSON
Sau thao tác ghi, Agent nên đọc lại tài nguyên trước khi tiếp tục
agentHints giúp giảm hành vi thực thi theo quán tính
CLI có thể đóng vai trò điều hướng workflow, không chỉ là bộ chạy lệnh
Lỗi cũng nên đi kèm hướng dẫn sửa lỗi để Agent có thể hành động

Tải xuống Apidog để thiết kế, giả lập, kiểm thử và tài liệu hóa API trong một không gian làm việc duy nhất. Tìm hiểu thêm về Apidog CLI để kiểm thử API bằng dòng lệnh, tự động hóa CI và xây dựng workflow cho AI Agent.

DEV Community

agentHints: Dạy CLIs giao tiếp với Agents

Khoảng cách trong đầu ra CLI

Những gì Agent thực sự cần

`agentHints`: Cấu trúc đầu ra cho Agent

Vấn đề: quán tính thực thi

Tại sao bước đọc lại quan trọng

Cách `agentHints` điều hướng Agent

Vai trò mới của CLI trong workflow Agent

Cây workflow tích hợp

Vòng lặp an toàn hơn với `agentHints`

So sánh: có và không có `agentHints`

Cách áp dụng pattern này cho CLI của bạn

1. Luôn trả về JSON có cấu trúc

2. Tách dữ liệu thực tế khỏi hướng dẫn

3. Với lỗi, trả về mã lỗi và bước khắc phục

4. Ưu tiên bước xác minh sau thao tác ghi

Tiếp theo là gì

Những điểm chính

Top comments (0)

Khoảng cách trong đầu ra CLI

Những gì Agent thực sự cần

agentHints: Cấu trúc đầu ra cho Agent

Vấn đề: quán tính thực thi

Tại sao bước đọc lại quan trọng

Cách agentHints điều hướng Agent

Vai trò mới của CLI trong workflow Agent

Cây workflow tích hợp

Vòng lặp an toàn hơn với agentHints

So sánh: có và không có agentHints

Cách áp dụng pattern này cho CLI của bạn

1. Luôn trả về JSON có cấu trúc

2. Tách dữ liệu thực tế khỏi hướng dẫn

3. Với lỗi, trả về mã lỗi và bước khắc phục

4. Ưu tiên bước xác minh sau thao tác ghi

Tiếp theo là gì

Những điểm chính

`agentHints`: Cấu trúc đầu ra cho Agent

Cách `agentHints` điều hướng Agent

Vòng lặp an toàn hơn với `agentHints`

So sánh: có và không có `agentHints`