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

Đây là một 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. Đọc theo thứ tự hoặc chuyển đến bất kỳ bài viết nào bạn quan tâm:

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

Khoảng cách về đầu ra của CLI

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

Điều này hiệu quả với con người. Con người có thể:

• Giải thích các thông báo mơ hồ
• Quyết định việc cần làm tiếp theo
• Ghi nhớ ngữ cảnh từ các lệnh trước đó
• Áp dụng kiến thức chuyên môn để tiếp tục

**Nhưng Agent hoạt động khác.**

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

Agent không chỉ đọc kết quả. Chúng cần **kết nối kết quả với chuỗi tác vụ tiếp theo.**

Một con người thấy "Tài nguyên được tạo thành công" và biết: "Tôi nên kiểm tra xem những gì đã được tạo, sau đó có thể chạy một số thử nghiệm."

Một Agent thấy "Tài nguyên được tạo thành công" và... không biết phải làm gì tiếp theo.

agentHints: Giải pháp

Apidog CLI thêm agentHints vào đầu ra của nó.

Đây là một ví dụ về phản hồi điển hình:

{
  "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."
    ]
  }
}

**Ba thành phần:**

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

Đây là một vấn đề thực tế mà chúng tôi đã quan sát:

**Sau khi tạo tài nguyên thành công, mô hình thường tiếp tục trực tiếp tạo lần ghi tiếp theo.**

Ví dụ:

Agent: Tạo trường hợp kiểm thử
CLI: Trả về thành công
Agent: Ngay lập tức tạo kịch bản kiểm thử (mà không đọc lại)
Agent: Ngay lập tức chạy kiểm thử
Kết quả: Kịch bản có cấu trúc sai, kiểm thử thất bại

Trong các quy trình nghiệp vụ phức tạp, **thực thi liên tục một cách máy móc là không phù hợp.**

Cách tiếp cận chính xác nhất thường là:

1. Tạo tài nguyên
2. **Đọc lại trước tiên**
3. Xác nhận cấu trúc
4. Sau đó tiếp tục

Tại sao việc đọc lại lại quan trọng

Bỏ qua việc đọc lại gây ra các vấn đề thực tế:

**Nếu cấu trúc thực tế không được đọc lại, Agent dễ dàng tiếp tục ghi dựa trên phỏng đoán của riêng nó—chứ không phải trên dữ liệu thực tế.**

agentHints như một điều hướng viên

agentHints biến trải nghiệm sản phẩm thành các gợi ý bước tiếp theo có thể đọc được bằng máy.

Nó xuất hiện **chính xác nơi Agent cần đưa ra quyết định.**

Ví dụ sau khi tạo một trường hợp kiểm thử:

{
  "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."
    ]
  }
}

Agent sẽ:

1. Đọc đầu ra
2. Phân tích cú pháp agentHints
3. Làm theo nextSteps[0]: đọc lại trường hợp kiểm thử
4. Xác nhận cấu trúc thực tế
5. Sau đó tiếp tục với thông tin chính xác

Chuyển đổi vai trò của CLI

Điều này thay đổi ý nghĩa của CLI trong quy trình làm việc của Agent.

**CLI trở thành một bộ điều hướng trạng thái nhẹ.**

Cây quy trình làm việc tích hợp

Apidog CLI có tích hợp **hàng nghìn quy trình làm việc có cấu trúc cây.**

Đây không chỉ là những gợi ý được mã hóa cứng. Chúng là:

Ví dụ sau khi cập nhật kịch bản kiểm thử 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ụ sau 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."
    ]
  }
}

**Ngay cả các lỗi cũng trở nên dễ điều hướng.**

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

Hãy cùng theo dõi một quy trình làm việc hoàn chỉnh với agentHints:

Bước 1: Agent tạo trường hợp kiểm thử
        ↓
Đầu ra CLI: thành công + agentHints
        ↓
agentHints.nextSteps[0]: "Đọc lại trường hợp kiểm thử đã tạo"
        ↓
Bước 2: Agent đọc lại (với cấu trúc thực tế)
        ↓
Đầu ra CLI: cấu trúc trường hợp kiểm thử + agentHints
        ↓
agentHints.nextSteps[0]: "Thêm các xác nhận nếu cần"
        ↓
Bước 3: Agent thêm các xác nhận (dựa trên cấu trúc thực tế)
        ↓
Đầu ra CLI: thành công + agentHints
        ↓
agentHints.nextSteps[0]: "Chạy kiểm thử"
        ↓
Bước 4: Agent chạy kiểm thử
        ↓
Đầu ra CLI: báo cáo kiểm thử

**Mọi bước đều được hướng dẫn. Không có bước nhảy mù quáng. Không có giả định.**

So sánh: Với và Không có agentHints

Tiếp theo là gì

Giờ đây CLI có thể hướng dẫn Agent qua các bước tiếp theo, câu hỏi còn lại là:

**Làm thế nào để Agent biết quy trình làm việc 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ẽ khám phá cách SKILL đóng gói kiến thức về quy trình làm việc—khi nào sử dụng lệnh, trình tự nào cần tuân theo và những trường nào không nên đoán.

Những điểm chính

• Đầu ra CLI truyền thống hướng về con người; Agent cần hướng dẫn có cấu trúc
• agentHints cung cấp tóm tắt + gợi ý các bước tiếp theo trong đầu ra JSON
• Quán tính thực thi khiến Agent bỏ qua việc đọc lại; agentHints ngăn chặn điều này
• CLI chuyển đổi từ bộ thực thi sang điều hướng viên
• Các cây quy trình làm việc tích hợp giúp mọi bước đều có thể điều hướng
• Ngay cả các lỗi cũng trở nên khả thi để hành động với agentHints

Tải xuống Apidog để thiết kế, giả lập, kiểm thử và tài liệu hóa các 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 dòng lệnh, tự động hóa CI và quy trình làm việc của AI Agent.