Skip to main content
The Canvas extension enables users to request edits to specific parts of artifacts (like code, documents, or other structured content) that your agent has generated. Instead of users describing what they want to change in text, they can select a portion of an artifact in the UI and request an edit, giving your agent precise information about what to modify.

How Canvas Works

When a user selects a portion of an artifact and requests an edit:
  1. The selection’s start and end indices (character positions) are captured.
  2. The user provides a description of what they want to change.
  3. The artifact ID identifies which artifact to edit.
  4. Your agent receives this structured information to process the edit request.
This allows your agent to:
  • Know exactly which part of the artifact the user wants to modify.
  • Access the original artifact content from history.
  • Make targeted edits based on the user’s description.
  • Generate a new artifact with the changes (using the same artifact_id to replace the previous version in the UI).

Example: Canvas with LLM

Here’s how to use canvas with an LLM, adapting your system prompt based on whether you’re generating new content or editing existing content:
1

Import the canvas extension

Import CanvasExtensionServer and CanvasExtensionSpec from agentstack_sdk.a2a.extensions.
2

Inject the extension

Add a canvas parameter to your agent function using the Annotated type hint with CanvasExtensionSpec().
3

Parse edit requests

Call await canvas.parse_canvas_edit_request(message=message) to check if the incoming message contains a canvas edit request. This returns None if no edit request is present, or a CanvasEditRequest object with:
start_indexThe starting character position of the selected text
end_indexThe ending character position of the selected text
descriptionThe user’s description of what they want to change
artifactThe full original artifact object from history
4

Access the original content

Extract the text from artifact.parts[0].root.text (for text artifacts) into a content variable and use the start/end indices to get the selected portion: selected_text = content[start_index:end_index].
5

Return a new artifact

Create a new artifact with your changes.

How to work with Canvas

Artifacts in history: The extension automatically retrieves the original artifact from history using the artifact_id. If not found, a ValueError is raised. Text parts filtering: The extension filters out fallback text messages (sent for agents that don’t support canvas) so you only work with structured edit request data.

Best Practices

Adapt your system prompt: Provide different instructions to your LLM depending on whether you’re generating new content or editing existing content. Validate indices: Ensure start and end indices are within bounds before slicing the artifact text.

Examples

For more examples, see: