User Prompt 도구

User Prompt 도구 (User Prompt Tool)

에이전트가 실행 중에 사용자에게 질문하고 입력을 받는 방법을 설명해요. 진행 전에 명확화, 확인, 추가 정보가 필요할 때 동작하는 대화형 워크플로를 만들어요.

출처: 문서

본문

user prompt 도구는 에이전트가 실행 중에 사용자에게 질문하고 입력을 수집하게 해 줘요. 에이전트가 진행 전에 명확화, 확인, 추가 정보가 필요한 대화형 워크플로를 가능하게 해요.

참고 언제 쓸까

  • 진행 전에 명확화가 필요할 때
  • 자격 증명이나 구성 값 수집
  • 선택지 제시하고 사용자 결정 받기
  • 파괴적이거나 중요한 작업 확인

구성

agents:
  assistant:
    model: openai/gpt-4o
    description: Interactive assistant
    instruction: |
      You are a helpful assistant. When you need information
      from the user, use the user_prompt tool to ask them.
    toolsets:
      - type: user_prompt
      - type: filesystem
      - type: shell

도구 인터페이스

user_prompt 도구는 다음 파라미터를 받아요:

파라미터 타입 필수 설명
message string ✓ 표시할 질문 또는 프롬프트
title string ✗ TUI에서 대화상자 창의 선택적 제목. 제공하지 않으면 "Question" 기본값
schema object ✗ 기대되는 응답 구조(객체 또는 기본형)를 정의하는 JSON Schema

응답 형식

도구는 JSON 응답을 반환해요:

{
  "action": "accept",
  "content": {
    "field1": "user value",
    "field2": true
  }
}

동작 값

동작 의미
accept 사용자가 응답을 제공했음(content 확인)
decline 사용자가 답하기를 거부
cancel 사용자가 프롬프트를 취소

스키마 예시

간단한 문자열 입력

{
  "type": "string",
  "title": "API Key",
  "description": "Enter your API key"
}

객관식

{
  "type": "string",
  "enum": ["development", "staging", "production"],
  "title": "Environment",
  "description": "Select the target environment"
}

불리언 확인

{
  "type": "boolean",
  "title": "Confirm",
  "description": "Are you sure you want to proceed?"
}

여러 필드가 있는 객체

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "description": "Your username"
    },
    "password": {
      "type": "string",
      "description": "Your password"
    },
    "remember": {
      "type": "boolean",
      "description": "Remember credentials"
    }
  },
  "required": ["username", "password"]
}

숫자 입력

{
  "type": "integer",
  "title": "Port Number",
  "description": "Enter the port number (1024-65535)",
  "minimum": 1024,
  "maximum": 65535
}

사용 예시

에이전트가 user prompt 도구를 쓰는 방법:

Agent: I need to deploy this application. Let me ask which environment to target.

[Calls user_prompt with message: "Which environment should I deploy to?"
 and schema with enum: ["development", "staging", "production"]]

User selects: "staging"

Agent: Great, I'll deploy to staging. Let me confirm this action.

[Calls user_prompt with message: "Deploy to staging? This will replace the current version."
 and schema with type: "boolean"]

User confirms: true

Agent: Deploying to staging...

UI 표시

프롬프트가 나타나는 방식은 인터페이스에 따라 달라요:

  • TUI: 적절한 입력 컨트롤이 있는 대화형 대화상자 표시
  • CLI(exec 모드): 프롬프트 인쇄하고 stdin에서 읽기
  • API/MCP: 클라이언트에 elicitation 요청 반환

팁 모범 사례 명확하고 간결한 메시지를 제공하세요. 왜 묻는지와 그 정보가 무엇에 쓰일지 맥락을 포함하세요. 기대되는 입력 형식을 안내하도록 설명이 있는 스키마를 사용하세요.

응답 처리

에이전트는 가능한 모든 동작을 처리해야 해요:

  • accept: 내용을 처리하고 계속
  • decline: 인정하고 대안 접근법을 시도하거나 무엇이 필요한지 설명
  • cancel: 현재 작업을 우아하게 중지

경고 컨텍스트 요구사항 user prompt 도구는 elicitation 핸들러가 구성되어 있어야 해요. TUI와 CLI 모드에서 동작하지만 일부 컨텍스트(예: 일부 MCP 클라이언트 구성)에서는 사용 불가능할 수 있어요.

더 알아보기 (Learn more)