Skip to main content
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.
pil_image.py
import base64
import io
from collections.abc import AsyncGenerator

from acp_sdk.models import Message, Artifact
from acp_sdk.server import Context, RunYield, RunYieldResume, Server
from PIL import Image, ImageDraw

server = Server()


@server.agent()
async def pil_image_generator(
    input: list[Message], context: Context
) -> AsyncGenerator[RunYield, RunYieldResume]:
    """Generates a simple PNG image using PIL and returns it."""
    img = Image.new("RGB", (100, 100), color="red")
    draw = ImageDraw.Draw(img)
    draw.text((10, 10), "ACP Image", fill="white")

    buffer = io.BytesIO()
    img.save(buffer, format="PNG")
    buffer.seek(0)

    yield Artifact(
        name="image.png",
        content=base64.b64encode(buffer.read()).decode("utf-8"),
        content_encoding="base64",
        content_type="image/png"
    )


server.run()
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 with name, content (base64 string), content_encoding="base64", and content_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.
json_artifact.py
import json
from collections.abc import AsyncGenerator

from acp_sdk.models import Message, Artifact
from acp_sdk.server import Context, RunYield, RunYieldResume, Server

server = Server()


@server.agent()
async def json_artifact_generator(
    input: list[Message], context: Context
) -> AsyncGenerator[RunYield, RunYieldResume]:
    """Generates a JSON artifact."""
    data = {
        "status": "success",
        "result": {
            "item_id": 123,
            "description": "Sample JSON data"
        }
    }

    yield Artifact(
        name="result.json",
        content=json.dumps(data, indent=2),
        content_type="application/json"
    )


server.run()
Key points:
  • A Python dictionary (data) holds the structured information.
  • json.dumps() converts the dictionary into a JSON string.
  • An Artifact is yielded with name, content (the JSON string), and content_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.