Generate Artifacts
Learn how to generate and return artifacts like images and structured data.
Artifacts are specialized message parts used to represent attachments, citations, files, or other named results. They are distinguished from regular message parts by the presence of a name
field. This allows agentic applications to implement specific semantics for handling these outputs, such as displaying structured metadata, enabling file downloads, or facilitating iterative workflows.
Refer to the Message Structure documentation for more details on the artifact definition.
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:
- The image is created in memory using Pillow.
- It’s saved to a
BytesIO
buffer. - The buffer’s content is base64 encoded, which is required for inlined binary data.
- 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.