Skip to main content

Artifact Management Tools

This guide details how agents utilize built-in tools to manage file artifacts and their associated metadata. The system employs an explicit, metadata-aware methodology wherein the agent maintains full control over the lifecycle of artifacts, including their creation, listing, loading, and return.

The Metadata-Aware Workflow​

Rather than automatically bundling all created artifacts in the final response, the agent follows a structured workflow:

  1. Create & Describe: The agent invokes the create_artifact tool to persist a file. Rich metadata, such as descriptions, sources, and inferred schemas, is stored alongside the artifact.
  2. Inject & Inform: This metadata is automatically injected into the conversation history, providing the agent with immediate context regarding the new file.
  3. List & Discover: The agent can call list_artifacts at any point to retrieve a summary of all available artifacts and their associated metadata.
  4. Load & Analyze: The agent can use load_artifact to read the content of a text-based artifact or inspect the detailed metadata of any artifact (for example, to ascertain the schema of a CSV file).
  5. Return on Request: To transmit an artifact to the user or a calling application, the agent must explicitly invoke signal_artifact_for_return. Artifacts are not returned automatically.

Configuration​

The file management tools are encapsulated within the artifact_management tool group.

Enabling the Tools​

Enable the tool group within the agent's app_config.yml:

# In your agent's app_config:
tools:
  - tool_type: builtin-group
    group_name: "artifact_management"

Configuring Artifact Return Behavior​

The artifact_handling_mode setting in your app_config dictates the behavior when signal_artifact_for_return is called:

  • ignore (Default): The request is logged, but no artifact is transmitted.
  • embed: The artifact content is base64-encoded and embedded within the TaskArtifactUpdateEvent payload. This is suitable for smaller files.
  • reference: A URI pointing to the artifact is sent in the event payload. This approach requires a separate service to host the file at the specified URI.
# In your agent's app_config:
artifact_handling_mode: "reference"

Tool Reference​

create_artifact​

Creates a new file artifact and its corresponding metadata.

  • Parameters:
    • filename (str): The designated name for the artifact (for example, "report.pdf").
    • content (str): The file content. For binary file types (for example, images, PDFs), this content must be base64-encoded.
    • mime_type (str): The standard MIME type of the content (for example, "text/plain", "image/png").
    • metadata (dict, optional): A dictionary containing custom metadata (for example, {"description": "Monthly sales data"}).
  • Returns: A dictionary confirming the successful persistence of the artifact.
  • Key Feature: Upon successful execution of this tool, a summary of the artifact's metadata is automatically injected into the conversation history, informing the agent of the new file's context.

list_artifacts​

Lists all available artifacts within the current session.

  • Parameters: None.
  • Returns: A list of file objects, each containing the filename, available versions, and a metadata_summary for the latest version.

load_artifact​

Loads the content or detailed metadata of a specific version of an artifact.

  • Parameters:
    • filename (str): The name of the artifact to be loaded.
    • version (int): The specific version number of the artifact to load.
    • load_metadata_only (bool, optional): If True, the tool returns the complete, detailed metadata dictionary instead of the artifact's content. This is useful for inspecting schemas or other metadata fields.
  • Returns:
    • If load_metadata_only=False: The artifact's content (for text-based files) or a basic information dictionary (for binary files).
    • If load_metadata_only=True: The complete metadata dictionary for the specified artifact version.

signal_artifact_for_return​

Instructs the system to transmit a specific artifact version to the caller.

  • Parameters:
    • filename (str): The name of the artifact to be returned.
    • version (int): The specific version number of the artifact to return.
  • Returns: A dictionary confirming that the request has been received.
  • Note: This tool functions as a signal. The actual transmission of the artifact is handled by the system in accordance with the configured artifact_handling_mode.

Key Concepts​

  • Explicit Control: Agents possess full, explicit control over the entire artifact lifecycle.
  • Metadata-Driven Context: The automatic injection and summarization of metadata are fundamental to providing agents with situational awareness.
  • Signaled Return: Artifacts are transmitted to the user only upon an explicit request from the agent via the signal_artifact_for_return tool.
  • Synergy with Embeds: These tools can be used in conjunction with Dynamic Embeds, such as «artifact_meta:report.csv», for more efficient file handling.