에이전트형 양식

선언적 API는 속성을 통해 표준 HTML <form> 요소를 WebMCP 도구로 변환합니다. 브라우저는 양식 입력에서 JSON 스키마를 합성하고 에이전트 상호작용을 처리합니다.

Angular 신호 양식: @angular/forms/signals의 form()로 빌드된 양식에 toolname/tooldescription를 추가하지 마세요. 대신 앱 제공자에 provideExperimentalWebMcpForms()를 추가하고 experimentalWebMcpTool: { name, description } 옵션을 form()에 전달합니다. 그러면 Angular는 명령형 API를 통해 양식을 등록하고, 신호 모델에서 스키마를 빌드하고, 유효성 검사 및 제출에 연결합니다. 두 접근 방식을 모두 사용하면 동일한 양식이 두 번 등록됩니다.

양식 속성

• toolname: 도구의 고유한 이름입니다.
• tooldescription: 도구의 기능과 에이전트가 도구를 사용해야 하는 경우입니다. 양식의 필드, 옵션 또는 제한사항을 나열하지 마세요. 브라우저는 이미 양식 컨트롤에서 빌드하는 스키마에 이를 포함하고 있습니다.
• toolautosubmit: (선택사항) 있는 경우 에이전트는 사용자 상호작용을 기다리지 않고 양식을 제출할 수 있습니다.
• toolparamdescription: (선택사항) JSON 스키마 내에서 속성 설명을 정의하는 방법을 제공합니다. 컨트롤의 옵션이나 제한사항을 반복하는 것이 아니라 값의 의미를 설명하는 데 사용합니다 (예: 샘플 값 사용).
  • 해결 순서: 브라우저는 toolparamdescription가 있는 경우 이를 사용합니다. 이 속성이 없으면 연결된 <label>의 textContent를 사용합니다(라벨 지정 가능한 하위 요소 건너뜀). 라벨이 없으면 aria-description로 대체됩니다.
  • 그룹화 (필드 세트): 관련 요소 그룹 (예: <input type="radio"> 버튼)에 설명을 연결하려면 가장 가까운 상위 <fieldset> 요소에 toolparamdescription를 배치하여 매개변수 그룹 전체에 적용되도록 합니다.

예

<form toolname="search-cars" 
      tooldescription="Perform a car make/model search" 
      toolautosubmit>
  <label for="make">Vehicle Make</label>
  <input type="text" id="make" name="make" required>
  
  <label for="model">Vehicle Model</label>
  <input type="text" id="model" name="model" toolparamdescription="e.g., 330i, F-150" required>
  
  <button type="submit">Search</button>
</form>

JavaScript에서 제출 처리

상담사가 양식을 제출하면 SubmitEvent에 agentInvoked (불리언) 및 respondWith(promise)가 포함됩니다.

document.querySelector('form').addEventListener('submit', (event) => {
  event.preventDefault();

  // Validate the form
  const formValidationErrors = myFormIsValid();

  if (formValidationErrors.length > 0) {
    if (event.agentInvoked) {
      const errorString =
        'Validation failed: ' +
        formValidationErrors
          .map((err) => `${err.field} (${err.message})`)
          .join(', ');

      event.respondWith(Promise.resolve(errorString));
    }
    return;
  }

  const resultPromise = performAsyncSearch(new FormData(event.target));

  // Return the result directly to the agent without navigation
  if (event.agentInvoked) {
    event.respondWith(resultPromise);
  }
});

수명 주기 이벤트

document.modelContext는 에이전트가 도구와 상호작용을 시작하거나 중지할 때 이벤트를 내보냅니다. 도구 실행이 시작되면 toolactivated가 실행되고 취소되면 toolcancel가 실행됩니다.

// Starting in Chrome 156, these events are dispatched on `document.modelContext`.
// Older versions dispatch them on `window`. Feature-detect the event handler
// property to pick the right target for backward compatibility.
const targetFor = (type, listener, options) =>
  (`on${type}` in (document.modelContext ?? {}) ? document.modelContext : window)
    .addEventListener(type, listener, options);

targetFor('toolactivated', ({ toolName }) => {
  console.log(`Tool "${toolName}" started execution.`);
});

targetFor('toolcancel', ({ toolName }) => {
  console.log(`Tool "${toolName}" execution is cancelled.`);
});

시각적 피드백 (CSS)

의사 클래스를 사용하여 상담사가 양식과 상호작용할 때 양식을 강조 표시합니다.

• :tool-form-active: 에이전트가 적극적으로 사용하는 <form> 요소에 적용됩니다.
• :tool-submit-active: 브라우저가 사용자 검토를 위해 일시중지될 때 제출 버튼에 적용됩니다(toolautosubmit가 생략된 경우).

form:tool-form-active {
  outline: 2px dashed blue;
  background-color: rgba(0, 0, 255, 0.05);
}

button:tool-submit-active {
  outline: 2px dashed red;
  animation: pulse 2s infinite;
}

양식 적합성 (피해야 하는 경우)

선언적 API는 독립적인 표준 양식에 가장 적합합니다. 다음과 같은 시나리오에서는 적합하지 않습니다.

• Highly Dependent Fields: 입력에 따라 다른 입력의 옵션이나 표시 여부가 변경되는 양식입니다. 합성된 스키마는 이러한 종속 항목을 잘 표현할 수 없습니다.
• 맞춤 UI 구성요소: 값을 자동 직렬화하지 않는 비표준 입력 (예: 캔버스, 서식 있는 텍스트 편집기)을 사용하는 양식입니다.
• 다단계 마법사: 여러 양식 제출이 필요한 복잡한 워크플로 이 경우 명령형 API 또는 표준 DOM 상호작용이 더 적합합니다.

toolautosubmit을 사용해야 하는 경우

• 읽기 전용 작업 및 쿼리: 검색, 필터링, 세부정보 가져오기, 상태 확인 (예: 자동차 모델 검색, 디렉터리 검색, 재고 확인)
• 위험도가 낮고 되돌릴 수 있는 작업: 사용자가 수동으로 쉽게 실행취소하거나 수정할 수 있는 양식 작업입니다 (예: 장바구니에 상품 추가, 쿠폰 코드 적용, 초안 저장, 임시 레이아웃 옵션 설정).

toolautosubmit를 생략해야 하는 경우

• 파괴적이거나 되돌릴 수 없는 작업: 레코드 삭제, 시스템 구성 재설정, 데이터베이스 삭제
• 금융 및 거래 작업: 결제 양식 제출, 송금, 정기 결제 승인, 최종 주문 등
• 영향력이 큰 사용자 커뮤니케이션: 최종 입사 지원서 제출, 다른 실제 사용자에게 이메일/메시지 전송, 공개 콘텐츠 게시
• 민감한 계정 설정: 비밀번호 변경, 사용자 역할/권한 수정, 결제/프로필 정보 업데이트

대체 전략

WebMCP Declarative API는 모든 브라우저에서 안전하게 사용할 수 있습니다. WebMCP를 지원하지 않는 브라우저는 tool* 속성을 무시하고 <form>는 일반 HTML 양식으로 계속 작동합니다. 기능 감지가 필요하지 않습니다.