Artifact Loading Tool

Purpose

The Artifact Loading Tool addresses the need for AI agents or large language models (LLMs) to dynamically access and incorporate the contents of stored artifacts within an ongoing session. Within the broader Tooling System framework that defines modular tools callable by agents or LLMs, this subtopic specializes in enabling agents to:

• Inform the LLM about available artifacts relevant to the session.

• Respond to LLM requests by loading specified artifacts on demand.

• Append artifact contents directly into the agent's context or instructions, enhancing the model's capability to reason about or act upon stored data.

This capability is essential because artifacts (such as files or blobs) managed by the Artifact Management topic are typically stored separately from session state. The tool bridges this gap by making artifact contents accessible during agent invocation without manual intervention.

Functionality

The Artifact Loading Tool implements a specialized tool interface that integrates into agent workflows and LLM instruction processing. Its core functionality includes the following key workflows:

1. Declaration as a Callable Tool

The tool registers itself with a function-like declaration named "load_artifacts", exposing a JSON schema describing its input parameter: a list of artifact names. This allows the LLM to understand how to call the tool via function calls during generation.

func (t *artifactsTool) Declaration() *genai.FunctionDeclaration {
    return &genai.FunctionDeclaration{
        Name:        t.name,
        Description: t.description,
        Parameters: &genai.Schema{
            Type: "OBJECT",
            Properties: map[string]*genai.Schema{
                "artifact_names": {
                    Type: "ARRAY",
                    Items: &genai.Schema{
                        Type: "STRING",
                    },
                },
            },
        },
    }
}

2. Injecting Initial Instructions

Before the LLM request is sent, the tool queries the artifact service for the list of available artifact filenames in the current session context. It then appends a system-level instruction to the LLM prompt:

• Listing all artifact names.

• Advising the LLM to use the load_artifacts function call to access any artifact content.

• Enforcing that the LLM should not generate text directly when referring to artifacts but instead must invoke the function call.

This instruction primes the model to interact with artifacts in a controlled, function-driven manner.

3. Processing LLM Function Calls

When the LLM emits a function call to load_artifacts with a list of artifact names, the tool concurrently loads each artifact's content from the artifact service using goroutines and an error group (errgroup). Each loaded artifact is wrapped into a genai.Content message and appended to the ongoing LLM request contents.

This process enables the LLM to receive the raw contents of requested artifacts in the next generation step, allowing it to reason or respond based on the actual data.

4. Type Safety and Error Handling

The tool carefully handles input argument types, converting from generic JSON-like values to typed string slices to ensure robustness. It also returns detailed errors if artifact loading fails or if inputs do not match expected schemas.

5. Integration with Agent Sessions

The tool operates on the tool.Context, which provides access to the artifact service scoped to the current session. This ensures that artifact loading respects user and session boundaries.

Integration

The Artifact Loading Tool integrates tightly with the Tooling System (80556), serving as a specific implementation of a tool that agents or LLMs can call. It complements other tools like function tools and search tools by focusing exclusively on artifact data retrieval.

Within the agent lifecycle (see Agent Execution Runner), the tool is involved in processing LLM requests:

• It packs itself into the LLM request as a callable function.

• It appends initial instructions based on available artifacts.

• It detects and handles LLM function calls to load artifacts, appending their content to the request to be consumed by subsequent LLM generations.

This subtopic also relates closely to:

• Artifact Management (80557), which provides the underlying service for storing and retrieving artifact data.

• Session Management (80559), since artifact loading occurs within the context of user-agent sessions.

• Instruction Template Processing (80563), as the tool appends instructions dynamically to the LLM prompt.

By making artifact contents available on demand, this tool enhances the agent's contextual awareness and ability to handle data-driven tasks, complementing other tools that provide function calls or external data lookup.

Diagram

sequenceDiagram
participant Agent as Agent
participant Tool as Artifact Loading Tool
participant LLM as LLM Model
participant ArtifactService as Artifact Service
Agent->>Tool: Prepare LLMRequest
Tool->>ArtifactService: List available artifact names
ArtifactService-->>Tool: Artifact name list
Tool->>LLM: Append instructions with artifact list
LLM->>Agent: Generates function call "load_artifacts" with artifact_names
Agent->>Tool: Detect function call in LLMRequest
Tool->>ArtifactService: Concurrently load artifacts by name
ArtifactService-->>Tool: Artifact contents
Tool->>Agent: Append artifact contents to LLMRequest
Agent->>LLM: Continue generation with artifact contents

This sequence illustrates how the tool participates in preparing the LLM request, instructing the model about available artifacts, detecting function calls during generation, loading artifact contents, and appending them for further LLM consumption.