tool_context.list_artifacts() Returns Empty List Even When Files Are Uploaded

[sudharshanredd445]

Issue: tool_context.list_artifacts() Returns Empty List Despite Files Being Uploaded

Description

When using ADK agents with file upload functionality, tool_context.list_artifacts() consistently returns an empty list even when files are successfully uploaded through the UI. Files uploaded via the ADK Web Developer UI or AgentSpace are not being detected by the list_artifacts() method, preventing agents from accessing uploaded files.

Environment

• ADK Version: google-cloud-aiplatform[adk,agent_engines]>=1.75.0
• Python Version: 3.12
• Deployment: Vertex AI Agent Engine (via reasoning_engines.AdkApp)
• Model: gemini-2.5-flash
• Location: europe-west1

Steps to Reproduce

1. Deploy an ADK agent with a tool that calls tool_context.list_artifacts()
2. Upload a file (PDF, image, etc.) through the ADK Web Developer UI or AgentSpace interface
3. The file upload appears successful in the UI
4. Agent tool calls await tool_context.list_artifacts()
5. The method returns an empty list [] instead of the uploaded file names

Expected Behavior

tool_context.list_artifacts() should return a list of artifact names/IDs for all files uploaded in the current session, allowing the agent to:

• List available files
• Load artifacts using tool_context.load_artifact(filename)
• Process uploaded files in agent tools

Actual Behavior

tool_context.list_artifacts() returns an empty list [] even when:

• Files are successfully uploaded and visible in the UI
• Files appear in the conversation as [Uploaded Artifact: "filename.pdf"] placeholders
• The file content is accessible via multimodal input (inline_data in user_content)

Code Example

from google.adk.tools import ToolContext, FunctionTool
from google.adk.agents import Agent

async def list_uploaded_files(tool_context: ToolContext) -> str:
    """List all uploaded files/artifacts available in the current session."""
    try:
        # This returns [] even when files are uploaded
        artifacts = await tool_context.list_artifacts()
        print(f"artifacts: {artifacts}")  # Prints: artifacts: []
        
        if not artifacts:
            return "No files are currently uploaded in this session."
        
        artifact_list = "\n".join([f"- {artifact}" for artifact in artifacts])
        return f"Available uploaded files:\n{artifact_list}"
    except Exception as e:
        return f"Error listing artifacts: {str(e)}"

root_agent = Agent(
    name="file_upload_agent",
    model="gemini-2.5-flash",
    tools=[FunctionTool(list_uploaded_files)],
)

Workarounds Attempted

1. Checking user_content directly: Accessing files via tool_context.user_content.parts with inline_data works, but this only provides files from the current message, not saved artifacts.

# This works for files in current message
if hasattr(tool_context, 'user_content') and tool_context.user_content:
    for part in tool_context.user_content.parts:
        if hasattr(part, 'inline_data') and part.inline_data:
            # File found here, but not in list_artifacts()

2. Checking invocation_context: Attempted to access files through tool_context._invocation_context.user_content - same limitation as above.

3. Using load_artifacts tool: The built-in load_artifacts tool also fails to detect uploaded files when list_artifacts() returns empty.

Additional Context

Deployment Configuration

from vertexai.preview import reasoning_engines

app = reasoning_engines.AdkApp(
    agent=root_agent,
    enable_tracing=True,
    display_name="Uploader Agent",
    description="Uploader Agent for file upload",
    env_vars=env_vars,
)

app.set_up()

remote_app = agent_engines.create(
    agent_engine=app,
    requirements=["google-cloud-aiplatform[adk,agent_engines]>=1.75.0"],
    extra_packages=["adk_file_upload"],
    env_vars=deployment_env_vars,
)

Observations

• Files uploaded through the UI are visible in the conversation as placeholders: [Uploaded Artifact: "filename.pdf"]
• The file content is accessible via multimodal input (can be seen in user_content.parts with inline_data)
• However, list_artifacts() does not include these files in its return value
• This suggests a disconnect between how files are stored/registered and how list_artifacts() queries them

Impact

This issue prevents agents from:

• Dynamically discovering uploaded files
• Building file management workflows
• Creating tools that work with multiple uploaded files
• Properly implementing file upload agents

Questions

1. Is there a specific way files need to be saved/registered for list_artifacts() to detect them?
2. Should files uploaded through the UI automatically appear in list_artifacts()?
3. Is there a configuration or setup step required for artifact listing to work?
4. Are there any known limitations or requirements for list_artifacts() in Agent Engine deployments?

Related Documentation

• ADK Artifacts Documentation
• ADK Tools Documentation

---

Note: This issue affects the core functionality of file upload agents. A fix or clarification on the expected behavior would be greatly appreciated.

[advaitvd]

Analysis & Clarification

I have investigated this behavior and successfully reproduced the scenario. In the current ADK architecture, uploading a file via the ADK Web UI provides the file as multimodal input (within the prompt's conversation context), but it does not automatically register that file as a persistent session artifact.

How to Register Artifacts

To make a file discoverable via tool_context.list_artifacts(), the content must be explicitly registered using the save_artifact method. This method is provided by the CallbackContext class (from which ToolContext is derived).

You can implement a tool to bridge this gap as follows:

from google.adk.tools import ToolContext
from google.cloud.aiplatform.v1beta1 import types

async def save_report_artifacts(tool_context: ToolContext,
                                report_data: str,
                                filename: str) -> str:
    """
    Saves the provided report data as an artifact with the given filename.
    
    Args:
        tool_context (ToolContext): The context for the tool execution.
        report_data (str): The content of the report to be saved.
        filename (str): The name of the file to save the report as.
    """
    # Data has to be encoded to bytes to be saved as an artifact.
    data_bytes = report_data.encode('utf-8')

    # Create an artifact part with the data.
    artifact_part = types.Part(
        inline_data=types.Blob(mime_type="text/plain", data=data_bytes),
    )

    # Use the ToolContext to save/register the artifact.
    await tool_context.save_artifact(filename, artifact_part)
    return f"Successfully registered {filename} as a session artifact."

Working Response

Seeking Clarification

To ensure this is addressed correctly in the roadmap:

• Feature Request: Is this issue highlighting a request to enable automatic artifact registration upon a simple UI upload (parity between UI state and ToolContext state)?

• Bug Report: Or were you encountering this as unexpected behavior based on specific documentation suggesting UI uploads should be immediately "listable"?

Clarifying this will help determine if the fix should be a framework-level "auto-register" feature or a documentation update.

[sudharshanredd445]

Thank you for the detailed explanation and for providing the save_artifact() workaround.
I have tested this approach, and I can confirm that explicitly calling tool_context.save_artifact() successfully registers the file and makes it discoverable through tool_context.list_artifacts(). This resolves the technical blocker on my side.

However, I’d like to clarify the intent of this issue for tracking purposes.

Summary of Understanding

Files uploaded through the ADK Web UI / AgentSpace UI are currently passed as multimodal prompt input.

These uploads are not automatically registered as persistent session artifacts.

Therefore, tool_context.list_artifacts() remains empty unless save_artifact() is explicitly called.

Requested Clarification / Enhancement

From a developer experience perspective, the UI visually presents uploaded files as “artifacts”, which naturally leads to the expectation that they would be discoverable through tool_context.list_artifacts() without additional manual registration.

So this issue should be categorized as:

Feature Request – to enable automatic registration of UI-uploaded files as session artifacts, or at least provide a configuration option to do so.

If automatic registration is not intended by design, then a documentation clarification would be helpful to explicitly state:

“Files uploaded via ADK Web UI are provided as multimodal prompt inputs only and must be explicitly saved using tool_context.save_artifact() if persistence and listing via list_artifacts() is required.”

Conclusion

The workaround solves the immediate problem.
My request is mainly for either:

UI → ToolContext automatic artifact parity, or

Clear documentation describing the current separation.

Thanks again for the prompt investigation and guidance. I’m happy to test future updates if needed.