google-adk-artifacts

name	google-adk-artifacts
description	ADK artifact services for file storage. Use when agents need to save/load files, images, or binary data — InMemory, File, and GCS artifact backends.

Google ADK — Artifacts

Overview

Artifacts are files (images, documents, data) that agents produce or consume. The ArtifactService handles versioned storage and retrieval.

Service	Persistence	Use Case
InMemoryArtifactService	None (RAM)	Development, testing
FileArtifactService	Local filesystem	Local persistence
GcsArtifactService	Google Cloud Storage	Production

Setup with Runner

from google.adk.agents import Agent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService

agent = Agent(
    name="my_agent",
    model="gemini-2.5-flash",
    instruction="...",
    tools=[generate_report],
)

runner = Runner(
    agent=agent,
    session_service=InMemorySessionService(),
    artifact_service=InMemoryArtifactService(),
    app_name="my_app",
)

Saving Artifacts (in Tools)

from google.adk.tools.tool_context import ToolContext
from google.genai import types

def generate_chart(data: str, tool_context: ToolContext) -> str:
    """Generates a chart image from data.

    Args:
        data: The data to chart.
    """
    image_bytes = create_chart(data)

    artifact = types.Part(
        inline_data=types.Blob(
            mime_type="image/png",
            data=image_bytes,
        )
    )

    version = tool_context.save_artifact(
        filename="chart.png",
        artifact=artifact,
    )
    return f"Chart saved (version {version})"

Loading Artifacts (in Tools)

from google.adk.tools.tool_context import ToolContext

def get_chart(tool_context: ToolContext) -> str:
    """Gets the latest chart.
    """
    artifact = tool_context.load_artifact(filename="chart.png")
    if artifact is None:
        return "No chart found."
    return f"Chart loaded: {artifact.inline_data.mime_type}"

Built-in load_artifacts Tool

ADK ships a load_artifacts tool that agents can use directly:

from google.adk.agents import Agent
from google.adk.tools import load_artifacts

agent = Agent(
    name="reader",
    model="gemini-2.5-flash",
    instruction="Help users view their saved files.",
    tools=[load_artifacts],
)

File Artifact Service (Local Persistence)

from google.adk.artifacts.file_artifact_service import FileArtifactService

artifact_service = FileArtifactService(base_dir="./artifacts")

GCS Artifact Service (Production)

from google.adk.artifacts.gcs_artifact_service import GcsArtifactService

artifact_service = GcsArtifactService(
    bucket_name="my-agent-artifacts",
    prefix="production/",
)

Artifact Versioning

Every save_artifact call increments the version (starting at 0):

def save_draft(text: str, tool_context: ToolContext) -> str:
    """Saves a draft document.

    Args:
        text: The draft content.
    """
    artifact = types.Part(text=text)
    version = tool_context.save_artifact(filename="draft.md", artifact=artifact)
    return f"Draft saved as version {version}"

def get_draft_version(version: int, tool_context: ToolContext) -> str:
    """Gets a specific draft version.

    Args:
        version: The version number to retrieve.
    """
    artifact = tool_context.load_artifact(filename="draft.md", version=version)
    if artifact is None:
        return "Version not found."
    return artifact.text

ArtifactService API

# Direct API (used internally, ToolContext wraps this)
await artifact_service.save_artifact(
    app_name="my_app",
    user_id="user_123",
    filename="report.pdf",
    artifact=types.Part(inline_data=types.Blob(mime_type="application/pdf", data=pdf_bytes)),
    session_id="session_abc",
    custom_metadata={"generated_by": "report_agent"},
)

artifact = await artifact_service.load_artifact(
    app_name="my_app",
    user_id="user_123",
    filename="report.pdf",
    session_id="session_abc",
    version=0,
)

Key Rules

• Artifacts are versioned — each save returns an incrementing version number
• Use tool_context.save_artifact() / tool_context.load_artifact() in tools
• filename is the artifact identifier (scoped to app + user + session)
• session_id=None makes the artifact user-scoped (accessible across sessions)
• Artifact content is stored as types.Part (text, inline_data, or file_data)
• InMemoryArtifactService loses data on restart — use File or GCS in production

Related Skills

• google-adk-session — Session services (peer to artifact services on Runner)
• google-adk-memory — Long-term memory (for conversation recall, not files)
• google-adk-function-tool — Creating tools that save/load artifacts