Artifacts

Artifacts permitem que agentes enviem conteudo estruturado e interativo para usuarios atraves do A2H Protocol (Agent-to-Human, versao 0.3). Em vez de descrever um formulario em texto, voce envia um formulario real que o usuario pode preencher.

Enviando um Artifact

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,
});

Atualizando um Artifact

Atualize um artifact enviado anteriormente para refletir progresso ou novo estado:

await agent.updateArtifact(conversationId, {
  ref_artifact: "artifact_id",
  revision: 2,  // Deve ser maior que a revisao atual
  updates: {
    status_block_key: {
      state: "done",
      label: "Completed",
    },
  },
});

Recebendo Respostas do Usuario

Quando um usuario interage com um artifact (envia um formulario, clica em um botao), a resposta chega via onEvent:

agent.onEvent((event) => {
  if (event.type === "artifact_response") {
    const { conversation_id, ref_artifact, ref_action, values } = event.payload;
    // values contem os dados do formulario enviados pelo usuario
  }
});

Tipos de Bloco

Artifacts sao compostos de blocos. Cada bloco tem uma tag que determina seu tipo:

Tag	Descricao	Exemplo de Uso
input	Entrada de texto, textarea, numero, data	Campos de formulario
select	Dropdown ou selecao radio	Listas de opcoes
checkbox	Toggle booleano	Confirmacoes
action	Botao (primary, secondary, danger)	Enviar, cancelar, aprovar/negar
text	Texto de exibicao estatico	Instrucoes, descricoes
status	Indicador de progresso	Barras de progresso de tarefas
table	Exibicao de dados tabulares	Resultados de busca, tabelas de dados
code	Codigo com destaque de sintaxe	Trechos de codigo
image	Imagem incorporada	Graficos, diagramas
divider	Separador visual	Quebras de secao

Subtipos de Artifact

Subtipo	Proposito
form	Coletar entrada do usuario
status	Exibir progresso de tarefa
result	Mostrar resultado final
error	Exibir informacoes de erro
table	Exibicao de dados estruturados
code	Exibicao de codigo com destaque de sintaxe

Limites

Restricao	Valor
Maximo de blocos por artifact	16
Tamanho maximo do payload A2H	64KB
Tamanho maximo total do payload (com envoltorio)	200KB
Maximo de atualizacoes por ciclo de vida do artifact	100
Encaminhavel por padrao	Nao

O Que o SDK Cuida

• Criptografar payloads de artifact antes do envio
• Construir texto de previa para notificacoes
• Rotear via WebSocket ou fallback REST
• Validar estrutura do payload

Proximos Passos

• Enviando Mensagens — Mensagens de texto e midia
• Streaming — Transmita respostas em tempo real
• Data Grants — Solicite acesso a dados do usuario