> ## Documentation Index
> Fetch the complete documentation index at: https://agentcommunicationprotocol.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/core-concepts/message-structure#artifact) 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.

```python pil_image.py theme={null}
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.

```python json_artifact.py theme={null}
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.