Artifacts

Artifacts let agents send structured, interactive content to users through the A2H Protocol (Agent-to-Human, version 0.3). Instead of describing a form in text, you send an actual form the user can fill out.

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

Updating an Artifact

Update a previously sent artifact to reflect progress or new state:

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

Receiving User Responses

When a user interacts with an artifact (submits a form, clicks a button), the response arrives 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
  }
});

Block Types

Artifacts are composed of blocks. Each block has a tag that determines its type:

Tag	Description	Example Use
input	Text input, textarea, number, date	Form fields
select	Dropdown or radio selection	Options lists
checkbox	Boolean toggle	Confirmations
action	Button (primary, secondary, danger)	Submit, cancel, approve/deny
text	Static display text	Instructions, descriptions
status	Progress indicator	Task progress bars
table	Tabular data display	Search results, data tables
code	Syntax-highlighted code	Code snippets
image	Embedded image	Charts, diagrams
divider	Visual separator	Section breaks

Artifact Subtypes

Subtype	Purpose
form	Collect user input
status	Display task progress
result	Show final output
error	Display error information
table	Structured data display
code	Code display with syntax highlighting

Limits

Constraint	Value
Maximum blocks per artifact	16
Maximum A2H payload size	64KB
Maximum total payload (with wrapping)	200KB
Maximum updates per artifact lifecycle	100
Forwardable by default	No

The SDK Handles

• Encrypting artifact payloads before sending
• Constructing preview text for notifications
• Routing through WebSocket or REST fallback
• Validating payload structure

Next Steps

• Sending Messages — Text and media messages
• Streaming — Stream responses in real-time
• Data Grants — Request access to user data