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.
1. The Metadata-Aware Workflow
Rather than automatically bundling all created artifacts in the final response, the agent follows a structured workflow:
- 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. - Inject & Inform: This metadata is automatically injected into the conversation history, providing the agent with immediate context regarding the new file.
- List & Discover: The agent can call
list_artifacts
at any point to retrieve a summary of all available artifacts and their associated metadata. - 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). - 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.
2. 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 theTaskArtifactUpdateEvent
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"
3. 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
, availableversions
, and ametadata_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): IfTrue
, 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.
- If
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
.
4. 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.