Open URL 도구

Open URL 도구 (Open URL Tool)

에이전트가 정의에 박혀 있는 URL을 사용자의 기본 브라우저로 여는 방법을 설명해요. 모델은 URL을 제공하지 않고 도구를 이름으로 호출만 해요.

출처: 문서

본문

open_url 도구셋은 인수 없는 단일 도구를 노출해요. 도구셋 정의에 박혀 있는 URL을 사용자의 기본 브라우저로 열어 주죠. 모델은 URL을 절대 제공하지 않아요 — 그냥 도구를 이름으로 호출해요. 브라우저 실행은 크로스 플랫폼이에요: Docker Agent는 macOS에서 open, Linux에서 xdg-open, Windows에서 rundll32를 사용해요.

참고 언제 쓸까

  • 에이전트가 온디맨드로 대시보드, 문서 페이지, 딥 링크를 열게 하기
  • 커스텀 URI 스킴으로 데스크톱 앱에 딥 링크하기(예: docker-desktop://)
  • 목적지가 고정되고 미리 알려진 "그곳으로 데려가 줘" 동작

구성

agents:
  assistant:
    model: openai/gpt-4o
    description: Assistant that can open the dashboard
    instruction: When the user asks to see the dashboard, call open_dashboard.
    toolsets:
      - type: open_url
        name: open_dashboard
        url: https://example.com/dashboard

속성

속성 타입 필수 설명
url string ✓ 열 URL. ${env.VAR} 보간 지원. OS가 디스패치할 수 있는 어떤 스킴이든 허용
name string ✗ 에이전트가 참조하는 도구 이름. 기본 open_url. 여러 개 구성할 때는 설명적인 이름을 쓰세요

여러 URL

목적지별로 도구셋 항목을 하나씩, 각각 자체 name으로 추가하세요:

toolsets:
  - type: open_url
    name: open_dashboard
    url: https://example.com/dashboard
  - type: open_url
    name: open_docs
    url: https://docs.example.com/${env.DOCS_VERSION}

URL 보간

url 필드는 ${env.VAR} 자리표시자를 지원하고, 호출 시점에 런타임 환경에 대해 확장돼요:

toolsets:
  - type: open_url
    name: open_docs
    url: https://docs.example.com/${env.DOCS_VERSION}

커스텀 URI 스킴

운영체제가 디스패치하는 법을 아는 어떤 스킴이든 동작해요. 데스크톱 애플리케이션으로의 딥 링크 포함:

toolsets:
  - type: open_url
    name: open_in_docker_desktop
    url: docker-desktop://dashboard/apps

한계

  • URL은 스킴(예: https://)을 포함해야 해요. 베어 경로는 거부돼요.
  • 커맨드라인 플래그처럼 보이는 URL(-로 시작)은 플랫폼 열기 헬퍼로의 인수 주입을 막기 위해 거부돼요.
  • 도구는 Docker Agent를 실행하는 호스트에서 URL을 열어요. 브라우저/런처가 없는 헤드리스나 원격 환경에서는 호출이 우아하게 실패하고 오류를 에이전트에 보고해요.

examples/open_url.yaml에서 완전한 구성을 확인하세요.

더 알아보기 (Learn more)