Generate Artifacts
Learn how to generate and return artifacts like images and structured data.
Artifacts are specialized message parts that represent named outputs like files, images, or structured data. Unlike regular text responses, artifacts have a name
field that allows consuming applications to implement specific handling semantics—such as offering downloads, displaying rich content, or enabling iterative workflows.
Common use cases for artifacts include:
- Generated files: Reports, images, or documents created by your agent
- Structured data: JSON, CSV, or XML for programmatic consumption
- Rich media: Images, charts, or visualizations
- Download assets: Files that users can save locally
Refer to the Message Structure documentation for detailed artifact specifications.
This guide demonstrates how to generate common artifact types like images and JSON data within your ACP agent.
Generating Image Artifacts
Agents can generate images dynamically and return them as artifacts. This example uses the Pillow (PIL) library to create a simple PNG image, encode it in base64, and yield it as an Artifact
message part.
Key points:
- Images must be base64 encoded for inline transmission
- Set
content_encoding="base64"
for binary data - Always handle potential image generation errors
- The content is saved to a
BytesIO
buffer - An
Artifact
is yielded withname
,content
(base64 string),content_encoding="base64"
, andcontent_type="image/png"
.
Generating JSON Artifacts
Agents can also return structured data, like JSON, as artifacts. This is useful for providing machine-readable output alongside or instead of human-readable text.
Key points:
- A Python dictionary (
data
) holds the structured information. json.dumps()
converts the dictionary into a JSON string.- An
Artifact
is yielded withname
,content
(the JSON string), andcontent_type="application/json"
. - The default
content_encoding
is"plain"
, which is suitable for JSON strings.
By generating artifacts, your agents can provide rich, structured outputs beyond simple text, enabling more sophisticated interactions and integrations.