artifact-handler

artifact-handler

ADK 2.0 separates large/binary content from session events via the ArtifactService. Use it for files, images, audio, and other non-text payloads.

Architecture

Session ──┬── events (text, tool calls, references)
          └── artifacts (blobs, stored separately)

Events stay small; artifacts are loaded on-demand by version.

In-memory artifacts (dev)

from google.adk.artifacts import InMemoryArtifactService
from google.adk.runners import Runner
from google.adk.agents import LlmAgent

artifact_service = InMemoryArtifactService()
runner = Runner(
    agent=root_agent,
    artifact_service=artifact_service,
)

Save an artifact from a tool

from google.adk.tools import ToolContext

async def generate_chart(data: list, ctx: ToolContext) -> dict:
    """Generate a PNG chart from data and store as an artifact."""
    import matplotlib.pyplot as plt, io
    fig, ax = plt.subplots()
    ax.plot(data)
    buf = io.BytesIO()
    fig.savefig(buf, format="png")
    buf.seek(0)

    artifact_id = await ctx.save_artifact(
        filename="chart.png",
        content=buf.read(),
        mime_type="image/png",
    )
    return {"artifact_id": artifact_id, "filename": "chart.png"}

Load an artifact in a downstream agent

async def annotate_chart(artifact_id: str, ctx: ToolContext) -> dict:
    """Load a chart artifact and add annotations."""
    art = await ctx.load_artifact(artifact_id)
    # art has: bytes, mime_type, filename, version, created_at
    annotated = add_annotations(art.bytes)
    new_id = await ctx.save_artifact(
        filename="chart_annotated.png",
        content=annotated,
        mime_type="image/png",
    )
    return {"artifact_id": new_id}

Persistent storage (production)

from google.adk.artifacts import GcsArtifactService

artifact_service = GcsArtifactService(
    bucket_name="my-adk-artifacts",
    project="my-project",
)

Stores artifacts in GCS; URLs signed on demand.

Versioning

Saving the same filename twice creates a new version. List versions:

versions = await artifact_service.list_artifact_versions(
    session_id=session.id,
    filename="chart.png",
)

Validation

• Artifact size under your storage backend's limit (GCS object size, etc.)
• MIME type set correctly so downstream tools can dispatch
• Cleanup policy in production (artifacts can grow unbounded)
• Test: tool saves artifact, agent references it, downstream agent loads same bytes

See also

• session-migrate — artifacts migrate alongside sessions when using export_session