Skip to content
Hashee Docs

Artifacts

아티팩트를 사용하면 에이전트가 A2H Protocol (Agent-to-Human, 버전 0.3)을 통해 구조화된 대화형 콘텐츠를 사용자에게 전송할 수 있습니다. 텍스트로 양식을 설명하는 대신, 사용자가 직접 작성할 수 있는 실제 양식을 전송합니다.

아티팩트 전송

await agent.sendArtifact(conversationId, {
  artifact: {
    a2h: "0.3",
    subtype: "form",
    blocks: [
      {
        tag: "input",
        key: "name",
        variant: "text",
        label: "Project name",
        required: true,
      },
      {
        tag: "input",
        key: "description",
        variant: "textarea",
        label: "Description",
      },
      {
        tag: "action",
        key: "submit",
        label: "Create Project",
        variant: "primary",
      },
    ],
  },
  title: "New Project Form",
  summary: "Fill in the project details",
  forwardable: false,
});

아티팩트 업데이트

이전에 전송한 아티팩트를 업데이트하여 진행 상태나 새로운 상태를 반영합니다:

await agent.updateArtifact(conversationId, {
  ref_artifact: "artifact_id",
  revision: 2,  // 현재 리비전보다 커야 함
  updates: {
    status_block_key: {
      state: "done",
      label: "Completed",
    },
  },
});

사용자 응답 수신

사용자가 아티팩트와 상호작용하면(양식 제출, 버튼 클릭) 응답이 onEvent를 통해 도착합니다:

agent.onEvent((event) => {
  if (event.type === "artifact_response") {
    const { conversation_id, ref_artifact, ref_action, values } = event.payload;
    // values에 사용자가 제출한 양식 데이터가 포함됨
  }
});

블록 유형

아티팩트는 블록으로 구성됩니다. 각 블록은 유형을 결정하는 tag를 가집니다:

태그설명사용 예
input텍스트 입력, 텍스트 영역, 숫자, 날짜양식 필드
select드롭다운 또는 라디오 선택옵션 목록
checkbox불리언 토글확인 사항
action버튼 (primary, secondary, danger)제출, 취소, 승인/거부
text정적 표시 텍스트안내, 설명
status진행률 표시기작업 진행률 바
table표 형식 데이터 표시검색 결과, 데이터 테이블
code구문 강조 코드코드 스니펫
image삽입된 이미지차트, 다이어그램
divider시각적 구분선섹션 구분

아티팩트 하위 유형

하위 유형목적
form사용자 입력 수집
status작업 진행 상태 표시
result최종 출력 표시
error오류 정보 표시
table구조화된 데이터 표시
code구문 강조가 포함된 코드 표시

제한 사항

제약 조건값
아티팩트당 최대 블록 수16
최대 A2H 페이로드 크기64KB
최대 총 페이로드 (래핑 포함)200KB
아티팩트 수명 주기당 최대 업데이트100
기본 전달 가능 여부아니오

SDK가 처리하는 것

  • 전송 전 아티팩트 페이로드 암호화
  • 알림용 미리보기 텍스트 구성
  • WebSocket 또는 REST 폴백을 통한 라우팅
  • 페이로드 구조 검증

다음 단계