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.
  • Custom Tool Integration: When building custom Python tools that need to process artifacts, you can use the Artifact type hint to have artifact content automatically loaded before your tool executes. For more information, see Working with Artifacts in Tools.