선언적 API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky
François Beaufort
François Beaufort
GitHub

게시일: 2026년 5월 18일

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

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

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

도구 등록

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

  • toolname: 도구의 목적에 따라 도구 이름을 명확하게 지정합니다.
  • tooldescription: 도구가 취하는 작업과 목적을 설명합니다.

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

<form toolname="createSupportRequest" tooldescription="Submits a request for customer 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를 사용해 보고 의견이 있으면 알려주세요.