선언적 API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

게시일: 2026년 5월 18일

설명하듯이 웹 확장 프로그램 Chrome 상태 의도
GitHub 개발자 체험판 개발자 무료 체험 개발자 체험판 개발자 무료 체험 View 실험 의도

선언적 API를 사용하여 주석을 추가하여 표준 HTML 양식을 WebMCP 도구로 변환합니다. 주석은 <form> 요소에서 도구의 이름과 목적을 정의하고 필드는 도구 매개변수 역할을 합니다. 브라우저는 이러한 요소를 에이전트가 명령형 도구와 유사하게 사용할 수 있는 구조화된 표현으로 변환합니다.

이 API를 사용하기 전에 예시 사용 사례를 읽어보세요.

도구 등록

폼에 다음 HTML 속성을 추가합니다.

  • toolname: 목적에 따라 도구의 이름을 명확하게 지정합니다.
  • tooldescription: 도구에서 취하는 조치와 목적을 설명합니다.

예를 들어 다음 양식은 example.com/get-customer-support에 있습니다.

<form toolname="supportRequestTool" tooldescription="Submit a request for support.">
</form>

에이전트가 toolname를 호출하면 브라우저가 양식에 포커스를 맞추고 필드를 채웁니다. 양식은 사용자에게 계속 표시됩니다.

toolname 또는 tooldescription HTML 속성을 삭제하면 도구가 등록 해제됩니다.

(선택사항) 도구 매개변수

정확성을 높이려면 개별 양식 요소에 다음 HTML 속성을 추가하세요.

  • toolparamdescription: 요소를 JSON 스키마 내의 속성 설명에 매핑합니다. 이 속성이 없으면 브라우저에서 연결된 <label> 내의 콘텐츠를 사용하고 라벨을 지정할 수 있는 하위 요소를 건너뜁니다. 라벨이 없으면 브라우저가 aria-description를 참조합니다.

다음 양식은 <select> 요소의 선택적 매개변수를 사용합니다.

<form toolname="supportRequestTool"
  tooldescription="Submit a request for support."
  action="/submit">

  <label for="firstName">First Name</label>
  <input type=text name=firstName>

  <label for="lastName">Last Name</label>
  <input type=text name=lastName>

  <select name="select" required toolparamtitle="Support type" 
    toolparamdescription="Determines what team this request is routed to.">
    <option value="Customer happiness team">Return my purchase.</option>
    <option value="Distribution team">Check where my package is.</option>
    <option value="Website support team">Get help on the website.</option>
  </select>

  <button type=submit>Submit</button>
</form>

브라우저는 이 양식을 다음 JSON으로 표현되는 도구로 해석합니다.

[
  {
    "name": "supportRequestTool",
    "description": "Submit a request for support.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "title": "firstName",
          "description": "First name"
        },
        "text": {
          "type": "string",
          "title": "lastName",
          "description": "Last name"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "title": "Support type",
          "description": "Determines what team this request is routed to."
        }
      },
      "required": [
        "select"
      ]
    }
  }
]

양식 제출

양식 제출에는 두 가지 선택사항이 있습니다.

  • 사용자가 제출을 수동으로 클릭하여 작업을 완료해야 합니다.
  • 제출 및 탐색 변경을 트리거하는 toolautosubmit 추가

SubmitEvent 인터페이스는 agentInvoked 불리언 속성을 도입합니다. 이 속성은 AI 에이전트에 의해 양식이 트리거될 때마다 true로 설정되어 에이전트 기반 상호작용에 맞게 웹 앱의 동작을 조정합니다.

또한 SubmitEvent에는 respondWith(Promise<any>) 메서드가 포함되어 있으므로 양식 결과로 확인되는 프로미스를 브라우저에 전달할 수 있습니다. 그런 다음 결과 값이 직렬화되어 모델에 도구의 출력으로 반환됩니다. 이 메서드를 사용하려면 먼저 preventDefault()를 호출하여 브라우저의 표준 양식 제출을 중지해야 합니다.

<form toolautosubmit toolname="search_tool"
  tooldescription="Search the web" action="/search">
  <input type=text name=query>
</form>
<script>
  document.querySelector("form").addEventListener("submit", (e) => {
    e.preventDefault();
    if (!myFormIsValid()) {
      if (e.agentInvoked) { e.respondWith(myFormValidationErrorPromise) };
      return;
    }
    if (e.agentInvoked) { e.respondWith(Promise.resolve("Search is done!")); }
  });
</script>

브라우저가 AI 에이전트가 "toolactivated" 이벤트로 도구를 실행했음을 알립니다. 양식 필드가 미리 채워지면 창에서 트리거됩니다. 반대로 사용자가 에이전트 작업을 취소하거나 reset() 메서드가 호출되면 "toolcancel" 이벤트가 트리거됩니다. 이 두 이벤트는 모두 취소할 수 없으며 식별을 위한 toolName 속성을 제공합니다.

window.addEventListener('toolactivated', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was activated.`);
  // TODO: Update UI or validate form if needed.
});

window.addEventListener('toolcancel', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was cancelled.`);
  // TODO: Let the user know. Update UI.
});

초점 표시기 수정

눈에 보이는 포커스 표시기는 사용자 및 상담사에게 페이지의 위치를 알리는 데 중요합니다. 에이전트가 도구를 성공적으로 호출하고, 연결된 양식에 포커스를 맞추고, 필드를 자동 입력하면 브라우저에서 시각적 피드백을 위한 특정 CSS 의사 클래스를 트리거합니다.

  • :tool-form-active는 도구의 HTML form 요소에 적용됩니다.
  • :tool-submit-active은 양식의 제출 버튼(있는 경우)에 적용됩니다.

이러한 클래스는 양식이 제출되거나, 상담사가 작업을 취소하거나, 사용자가 양식을 재설정하면 비활성화됩니다. 이러한 상태의 CSS를 맞춤설정하거나 기본 브라우저 스타일을 사용할 수 있습니다.

/* Chrome default declarative form styles. */
form:tool-form-active {
  outline: light-dark(blue, cyan) dashed 1px;
  outline-offset: -1px;
}

input:tool-submit-active {
  outline: light-dark(red, pink) dashed 1px;
  outline-offset: -1px;
}

포커스 권장사항 및 스타일에 대해 자세히 알아보세요.

참여 및 의견 공유

WebMCP는 현재 논의 중이며 향후 변경될 수 있습니다. 이 API를 사용해 보고 의견이 있다면 언제든지 알려주세요.