agentHints: 명령줄 인터페이스와 에이전트 소통 방법

이것은 Apidog이 API 테스트 및 API 라이프사이클 관리를 위한 명령줄 도구인 Apidog CLI를 개발한 방법을 공유하는 10부작 시리즈입니다. 순서대로 읽거나 관심 있는 게시물로 바로 이동하세요:

전통적인 CLI 출력은 사람을 위한 것입니다. Agent는 구조화된 결과, 실패 원인, 다음 단계 제안이 필요합니다. agentHints는 제품 경험을 기계가 읽을 수 있는 지침으로 변환합니다.

CLI 출력의 간극

전통적인 CLI 출력은 사람을 위해 설계되었습니다.

이것은 사람에게는 통합니다. 사람은 다음을 할 수 있습니다:

• 모호한 메시지 해석
• 다음에 무엇을 할지 결정
• 이전 명령의 맥락 기억
• 도메인 지식을 적용하여 진행

하지만 Agent는 다르게 작동합니다.

Agent에게 실제로 필요한 것

Agent는 단순히 결과를 읽는 것을 넘어섭니다. 그들은 결과를 다음 작업 체인에 연결해야 합니다.

사람은 "리소스가 성공적으로 생성되었습니다"라는 메시지를 보고 "무엇이 생성되었는지 확인한 다음, 테스트를 실행해야 할 것 같다"고 생각합니다.

Agent는 "리소스가 성공적으로 생성되었습니다"라는 메시지를 보고... 다음에 무엇을 해야 할지 알지 못합니다.

agentHints: 해결책

Apidog CLI는 출력에 agentHints를 추가합니다.

일반적인 응답은 다음과 같습니다:

{
  "success": true,
  "data": {
    "id": "12345",
    "name": "Health Check Test Case"
  },
  "agentHints": {
    "summary": "테스트 케이스가 성공적으로 생성되었습니다.",
    "nextSteps": [
      "생성된 테스트 케이스를 다시 읽어 구조를 확인하세요.",
      "테스트 케이스에 응답 유효성 검사가 필요한 경우 어설션을 추가하세요.",
      "통합 테스트를 위해 테스트 케이스를 테스트 시나리오에 추가하세요.",
      "시나리오에 추가한 후 관련 테스트를 실행하세요."
    ]
  }
}

세 가지 구성 요소:

실행 관성 문제

우리가 관찰한 실제 문제는 다음과 같습니다:

리소스를 성공적으로 생성한 후, 모델은 다음 쓰기 작업을 직접 생성하는 경우가 많습니다.

예시:

Agent: 테스트 케이스 생성
CLI: 성공 반환
Agent: 즉시 테스트 시나리오 생성 (다시 읽지 않고)
Agent: 즉시 테스트 실행
결과: 시나리오 구조가 잘못되어 테스트 실패

복잡한 비즈니스 프로세스에서는 기계적인 연속 실행이 적절하지 않습니다.

가장 올바른 접근 방식은 종종 다음과 같습니다:

1. 리소스 생성
2. 먼저 다시 읽기
3. 구조 확인
4. 그 다음 진행

다시 읽기가 중요한 이유

다시 읽기를 건너뛰면 실제 문제가 발생합니다:

실제 구조를 다시 읽지 않으면, Agent는 실제 데이터가 아닌 자신의 추측에 기반하여 쉽게 쓰기 작업을 계속합니다.

내비게이터로서의 agentHints

agentHints는 제품 경험을 기계가 읽을 수 있는 다음 단계 제안으로 변환합니다.

이것은 Agent가 결정을 내려야 하는 정확한 지점에 나타납니다.

테스트 케이스 생성 후 예시:

{
  "agentHints": {
    "nextSteps": [
      "--with-case-detail 플래그를 사용하여 생성된 테스트 케이스를 다시 읽으세요.",
      "쓰기 전에 cli-schema로 모든 업데이트를 검증하세요.",
      "테스트 시나리오 완료 후 테스트를 실행하세요."
    ]
  }
}

Agent는 다음을 수행합니다:

1. 출력을 읽습니다
2. agentHints를 파싱합니다
3. nextSteps[0]을 따릅니다: 테스트 케이스를 다시 읽습니다
4. 실제 구조를 확인합니다
5. 그런 다음 정확한 정보로 진행합니다

CLI 역할의 변화

이것은 Agent 워크플로에서 CLI의 의미를 바꿉니다.

CLI는 경량 상태 내비게이터가 됩니다.

내장된 워크플로 트리

Apidog CLI에는 수천 개의 트리 구조 워크플로가 내장되어 있습니다.

이것들은 단순히 하드코딩된 제안이 아닙니다. 다음을 포함합니다:

테스트 시나리오 업데이트 성공 후 예시:

{
  "agentHints": {
    "summary": "테스트 시나리오가 성공적으로 업데이트되었습니다.",
    "nextSteps": [
      "변경 사항을 확인하기 위해 테스트 시나리오를 실행하세요.",
      "실패가 있는지 테스트 보고서를 확인하세요.",
      "실패가 발생하면 디버깅을 위해 시나리오 단계를 다시 읽으세요."
    ]
  }
}

유효성 검사 실패 후 예시:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'comparator' has invalid value",
    "details": [...]
  },
  "agentHints": {
    "summary": "유효성 검사에 실패했습니다. 오류를 수정하고 다시 검증하세요.",
    "nextSteps": [
      "출력에서 오류 세부 정보를 검토하세요.",
      "오류 제안에 따라 JSON 파일을 조정하세요.",
      "쓰기 전에 cli-schema validate를 다시 실행하세요."
    ]
  }
}

실패조차도 탐색 가능하게 됩니다.

agentHints를 사용한 더 안전한 루프

agentHints를 사용한 완전한 워크플로를 추적해 봅시다:

1단계: Agent가 테스트 케이스를 생성합니다
        ↓
CLI 출력: 성공 + agentHints
        ↓
agentHints.nextSteps[0]: "생성된 테스트 케이스를 다시 읽으세요"
        ↓
2단계: Agent가 다시 읽습니다 (실제 구조 포함)
        ↓
CLI 출력: 테스트 케이스 구조 + agentHints
        ↓
agentHints.nextSteps[0]: "필요한 경우 어설션을 추가하세요"
        ↓
3단계: Agent가 어설션을 추가합니다 (실제 구조 기반)
        ↓
CLI 출력: 성공 + agentHints
        ↓
agentHints.nextSteps[0]: "테스트 실행"
        ↓
4단계: Agent가 테스트를 실행합니다
        ↓
CLI 출력: 테스트 보고서

모든 단계가 안내됩니다. 맹목적인 건너뛰기나 가정이 없습니다.

agentHints 사용 유무 비교

다음 단계

이제 CLI가 Agent에게 다음 단계를 안내할 수 있게 되었으니, 남은 질문은 다음과 같습니다:

Agent는 애초에 어떤 워크플로를 따라야 하는지 어떻게 알까요?

5부, SKILL: 운영 경험을 코드로 배포하기에서는 SKILL이 워크플로 지식(명령어를 언제 사용하고, 어떤 순서를 따라야 하며, 어떤 필드를 추측해서는 안 되는지)을 어떻게 패키징하는지 살펴볼 것입니다.

핵심 요점

• 전통적인 CLI 출력은 사람 중심입니다; Agent는 구조화된 안내가 필요합니다
• agentHints는 JSON 출력에서 요약 + 다음 단계 제안을 제공합니다
• 실행 관성으로 인해 Agent는 다시 읽기를 건너뛰지만, agentHints가 이를 방지합니다
• CLI는 실행자에서 내비게이터로 전환됩니다
• 내장된 워크플로 트리는 모든 단계를 탐색 가능하게 합니다
• agentHints를 통해 실패조차도 실행 가능하게 됩니다

단일 워크스페이스에서 API를 설계, 목업, 테스트 및 문서화하려면 Apidog을 다운로드하세요. 명령줄 API 테스트, CI 자동화 및 AI Agent 워크플로를 위한 Apidog CLI에 대해 자세히 알아보세요.