Artifact Builders

Artifact builders live in aion.core and are shared across all frameworks. Use them to construct a2a.types.Artifact objects before passing them to emit_artifact() or thread.post().

from aion.core.a2a import url_artifact, file_artifact, data_artifact

`url_artifact`

url_artifact(
    url: str,
    *,
    mime_type: str,
    name: str | None = None,
    artifact_id: str | None = None,
) -> Artifact

Build an artifact referencing a remote file by URL.

Parameter	Description
`url`	Remote file URL (e.g. `"https://cdn.example.com/report.pdf"`).
`mime_type`	MIME type of the file (e.g. `"application/pdf"`, `"image/png"`).
`name`	Human-readable artifact name. Defaults to `"file"`.
`artifact_id`	Explicit artifact ID. Auto-generated if not provided.

Returns: a2a.types.Artifact with a single FilePart (FileWithUri).

url_artifact("https://example.com/report.pdf", mime_type="application/pdf", name="report")

`file_artifact`

file_artifact(
    data: bytes,
    *,
    mime_type: str,
    name: str | None = None,
    artifact_id: str | None = None,
    file_action: FileActionPayload | None = None,
) -> Artifact

Build an artifact carrying inline file content as bytes.

Parameter	Description
`data`	File content as `bytes`.
`mime_type`	MIME type of the file (e.g. `"text/plain"`, `"image/png"`).
`name`	Human-readable artifact name. Defaults to `"file"`.
`artifact_id`	Explicit artifact ID. Auto-generated if not provided.

Returns: a2a.types.Artifact with a single FilePart (FileWithBytes). Raises: TypeError if data is not bytes.

file_artifact(pdf_bytes, mime_type="application/pdf", name="report")

The optional file_action parameter accepts a FileActionPayload from aion.core.a2a. The builder attaches it to the file part and declares the Messaging extension on the artifact.

File retention

With FILE_STORAGE_BACKEND=aion, the SDK uploads inline files as protected agent artifacts. Without a FileActionPayload, the SDK requests 30-day retention. An action with an omitted or None deadline requests indefinite storage.

Retention choice	Result
No `file_action`	The SDK requests 30 days.
Explicit UTC `datetime`	The SDK requests that absolute deadline.
Action with omitted or `None` `retention_expires_at`	The SDK requests indefinite storage.

from datetime import datetime, timezone
from aion.core.a2a import FileActionPayload, file_artifact

# Default: 30 days with the Aion file provider.
report = file_artifact(pdf_bytes, mime_type="application/pdf", name="report.pdf")

# An explicit deadline. Use FileActionPayload() for indefinite storage.
report = file_artifact(
    pdf_bytes,
    mime_type="application/pdf",
    name="report.pdf",
    file_action=FileActionPayload(
        retention_expires_at=datetime(2027, 1, 1, tzinfo=timezone.utc),
    ),
)

Use a future UTC deadline. The low-level AionFileClient follows the File Service contract: an absent deadline means indefinite storage. The 30-day default belongs to the SDK’s automatic Aion file provider, not the File Service or other storage providers. Download links expire separately, normally after one hour. A file action does not renew an existing URL or grant. Without a file backend, the builder keeps content inline and does not establish a storage deadline.

`data_artifact`

data_artifact(
    data: dict,
    *,
    name: str | None = None,
    artifact_id: str | None = None,
) -> Artifact

Build an artifact carrying structured JSON data.

Parameter	Description
`data`	JSON-serializable dict.
`name`	Human-readable artifact name. Defaults to `"data"`.
`artifact_id`	Explicit artifact ID. Auto-generated if not provided.

Returns: a2a.types.Artifact with a single DataPart (Protobuf Value).

data_artifact({"status": "ok", "score": 0.95}, name="result")

Full Example

from aion.core.a2a import data_artifact, file_artifact, url_artifact

# Remote file
report = url_artifact("https://example.com/report.pdf", mime_type="application/pdf", name="report")

# Inline bytes
thumbnail = file_artifact(image_bytes, mime_type="image/png", name="thumbnail")

# Structured data
metrics = data_artifact({"accuracy": 0.95, "latency_ms": 120}, name="metrics")

Card — the other builder shared across frameworks
Streaming Delta Semantics

What these builders return is passed to emit_artifact(), documented under the framework you are writing for.

Python SDK

LangGraph

Google ADK

`url_artifact`

`file_artifact`

File retention

`data_artifact`

Full Example

​url_artifact

​file_artifact

​File retention

​data_artifact

​Full Example

​Related Pages

`url_artifact`

`file_artifact`

File retention

`data_artifact`

Full Example

Related Pages