load_artifacts_tool.go

Overview

The load_artifacts_tool.go file implements the Artifact Loading Tool, a specialized tool within the tooling framework that enables AI agents or large language models (LLMs) to dynamically access and incorporate stored artifacts (e.g., files or blobs) during an agent session. This tool informs the model about available artifacts and provides their content on demand through function calls, allowing agents to respond to queries involving external data stored as artifacts.

Key capabilities include:

• Registering a callable function declaration (load_artifacts) that the LLM can invoke.

• Injecting initial instructions into the LLM request describing available artifacts.

• Processing LLM function call responses to load specified artifacts concurrently.

• Appending loaded artifact contents back into the session for further reasoning.

This tool operates within the session context (tool.Context) and interacts closely with the artifact service (agent.Artifacts), integrating tightly with the overall agent lifecycle and tooling system as described in Tooling System and Artifact Loading Tool.

Types

artifactsTool

Implements the tool.Tool interface representing the artifact loading tool.

Fields:

Functions and Methods

New() tool.Tool

Creates and returns a new instance of artifactsTool.

Usage Example:

tool := loadartifactstool.New()
fmt.Println(tool.Name())        // Output: "load_artifacts"
fmt.Println(tool.Description()) // Output: "Loads the artifacts and adds them to the session."

(t *artifactsTool) Name() string

Returns the tool's name identifier.

(t *artifactsTool) Description() string

Returns the tool's human-readable description.

(t *artifactsTool) IsLongRunning() bool

Indicates whether the tool performs long-running operations.

Returns: false — the artifact loading operations are designed to be quick and non-blocking.

(t *artifactsTool) Declaration() *genai.FunctionDeclaration

Returns a GenAI function declaration describing the tool's callable interface.

The declaration specifies:

• Function name: "load_artifacts"

• Description: Tool's description.

• Parameters: JSON schema with a single property "artifact_names" (an array of strings).

This declaration enables the LLM to understand the function signature for making function calls during generation.

(t *artifactsTool) Run(ctx tool.Context, args any) (map[string]any, error)

Executes the tool's core logic when invoked via a function call.

Parameters:

• ctx – The tool invocation context providing access to the artifact service and session.

• args – Arguments passed by the LLM; expected to be a map with key "artifact_names".

Behavior:

• Parses and validates the input argument "artifact_names" as a slice of strings.

• Returns a result map containing the "artifact_names" slice.

• Performs error handling for invalid argument types or JSON marshaling/unmarshaling failures.

Returns:

• A map with key "artifact_names" and value []string.

• An error if inputs are invalid.

Usage Example:

result, err := tool.Run(ctx, map[string]any{
    "artifact_names": []string{"file1.txt", "config.json"},
})
if err != nil {
    // handle error
}
// result["artifact_names"] is []string{"file1.txt", "config.json"}

(t *artifactsTool) ProcessRequest(ctx tool.Context, req *model.LLMRequest) error

Integrates the tool into the agent request lifecycle by:

1. Packing the tool into the LLM request tools list.

2. Appending initial instructions listing available artifacts.

3. Detecting and processing function calls to load_artifacts in the request contents.

Parameters:

• ctx – Tool context for current invocation.

• req – Pointer to the LLM request structure.

Returns:

• An error if packing, instruction appending, or function call processing fails.

(t *artifactsTool) appendInitialInstructions(ctx tool.Context, req *model.LLMRequest) error

Queries the artifact service to list all available artifact filenames and appends an instruction to the LLM request.

Instruction Content Highlights:

• Lists all artifact names.

• Instructs the LLM to always invoke the load_artifacts function to access artifact content rather than generating free text.

• Emphasizes that artifacts must be loaded on-demand, even if previously loaded.

Returns: Error on failure to list or marshal artifact names.

(t *artifactsTool) processLoadArtifactsFunctionCall(ctx tool.Context, req *model.LLMRequest) error

Detects if the last LLM request content contains a function call to load_artifacts. If so:

• Extracts the list of artifact names requested.

• Concurrently loads each artifact's content from the artifact service using goroutines and an errgroup.

• Wraps each loaded artifact content into genai.Content objects, prepending a descriptive text part.

• Appends the loaded contents to the request contents for subsequent LLM consumption.

Returns: An error if loading fails or input types are invalid.

(t *artifactsTool) loadIndividualArtifact(ctx context.Context, artifactsService agent.Artifacts, artifactName string) (*genai.Content, error)

Loads the content of a single artifact from the artifact service.

Parameters:

• ctx – Context for cancellation and deadlines.

• artifactsService – Interface for loading artifacts.

• artifactName – Name of the artifact to load.

Returns:

• *genai.Content containing a text part describing the artifact and the actual artifact content part.

• An error if loading fails.

Important Implementation Details

• Type Safety: The method Run marshals and unmarshals JSON to convert from generic any (interface{}) input to a typed []string, ensuring compatibility with dynamic LLM-generated inputs.

• Concurrent Artifact Loading: The method processLoadArtifactsFunctionCall uses errgroup to load multiple artifacts concurrently, improving efficiency especially when many artifacts are requested.

• Appending Instructions: Initial instructions appended to the LLM request explicitly guide the language model to invoke the tool function rather than generating unstructured text, enabling controlled artifact content retrieval.

• Integration with Agent and Artifact Services: The tool operates within the tool.Context which provides access to artifact management (Artifact Management) scoped to the current session, ensuring correctness and security.

Interaction with Other Components

• Tooling System: Implements the tool.Tool interface, integrating with the agent's toolset and lifecycle (Tooling System).

• Artifact Service: Uses the agent.Artifacts interface to list and load artifact contents from persistent storage (Artifact Management).

• LLMRequest: Modifies the LLM request by packing tool declarations, appending instructions (Instruction Template Processing), and injecting artifact contents upon function call responses.

• Agent Lifecycle: Operates during agent invocation phases, processing user queries and enriching interaction context with artifact data (LLM Integration and Agents).

Usage Workflow

sequenceDiagram
participant Agent
participant LoadArtifactsTool as Tool
participant LLMModel as LLM
participant ArtifactService as Artifacts
Agent->>Tool: ProcessRequest (LLMRequest)
Tool->>ArtifactService: List available artifacts
ArtifactService-->>Tool: Return artifact name list
Tool->>LLMModel: Append instructions with artifact list
LLMModel->>Agent: Generate function call "load_artifacts" with artifact_names
Agent->>Tool: Detect function call in LLMRequest
Tool->>ArtifactService: Concurrently load requested artifacts
ArtifactService-->>Tool: Return artifact contents
Tool->>Agent: Append artifact contents to LLMRequest
Agent->>LLMModel: Continue generation using artifact contents

Summary

The loadartifactstool provides an essential interface bridging stored artifact data with AI agents' reasoning processes via structured function calls. By integrating with artifact management and the tooling framework, it enables dynamic, on-demand retrieval and inclusion of artifact contents, enhancing the agent's contextual awareness and response capability in a safe, efficient manner. This closely aligns with the goals and architecture discussed in Artifact Loading Tool and the broader Tooling System.