Artifacts

Artifacts laten agents gestructureerde, interactieve inhoud naar gebruikers sturen via het A2H Protocol (Agent-to-Human, versie 0.3). In plaats van een formulier in tekst te beschrijven, stuur je een echt formulier dat de gebruiker kan invullen.

Een Artifact versturen

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

Een Artifact bijwerken

Werk een eerder verstuurd artifact bij om voortgang of een nieuwe status weer te geven:

await agent.updateArtifact(conversationId, {
  ref_artifact: "artifact_id",
  revision: 2,  // Must be greater than the current revision
  updates: {
    status_block_key: {
      state: "done",
      label: "Completed",
    },
  },
});

Gebruikersreacties ontvangen

Wanneer een gebruiker interacteert met een artifact (formulier indient, knop klikt), komt de reactie binnen via onEvent:

agent.onEvent((event) => {
  if (event.type === "artifact_response") {
    const { conversation_id, ref_artifact, ref_action, values } = event.payload;
    // values contains the form data submitted by the user
  }
});

Bloktypen

Artifacts zijn samengesteld uit blokken. Elk blok heeft een tag die het type bepaalt:

Tag	Beschrijving	Voorbeeldgebruik
input	Tekstinvoer, textarea, nummer, datum	Formuliervelden
select	Dropdown of radio-selectie	Optielijsten
checkbox	Booleaanse schakelaar	Bevestigingen
action	Knop (primary, secondary, danger)	Verzenden, annuleren, goedkeuren/weigeren
text	Statische weergavetekst	Instructies, beschrijvingen
status	Voortgangsindicator	Taakvoortgangsbalken
table	Tabelgegevens weergave	Zoekresultaten, gegevenstabellen
code	Syntax-gemarkeerde code	Codefragmenten
image	Ingesloten afbeelding	Grafieken, diagrammen
divider	Visuele scheiding	Sectie-overgangen

Artifact-subtypes

Subtype	Doel
form	Gebruikersinvoer verzamelen
status	Taakvoortgang weergeven
result	Eindresultaat tonen
error	Foutinformatie weergeven
table	Gestructureerde gegevensweergave
code	Codeweergave met syntax-markering

Limieten

Beperking	Waarde
Maximale blokken per artifact	16
Maximale A2H-payloadgrootte	64KB
Maximale totale payload (met wrapping)	200KB
Maximale updates per artifact-levenscyclus	100
Standaard doorstuurbaar	Nee

De SDK handelt af

• Artifact-payloads versleutelen voor verzending
• Voorbeeldtekst samenstellen voor meldingen
• Routering via WebSocket of REST-fallback
• Payloadstructuur valideren

Volgende stappen

• Berichten versturen — Tekst- en mediaberichten
• Streaming — Stream reacties in realtime
• Data Grants — Toegang aanvragen tot gebruikersgegevens