Recommended way to handle files not directly supported by Gemini

[vikramsg]

Currently I have a requirement to be able to read .xlsx files. However this is not supported by Gemini so if I follow the usual workflow either by passing in as an artifact or directly in prompt, ADK errors out.
https://ai.google.dev/gemini-api/docs/document-processing?lang=python#technical-details

The workaround is that I create tools to be able to read excel files and pass it back to the agent, however the issue is that this workaround doesn't quite work on adk web. I have to separate out file handling from the Agent.

What is the recommended way to tackle this issue? I want to be able to both use it as a workflow from the command line as well as in adk web.

[hangfei]

@adk-bot

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: The recommended approach is to create a custom tool to handle .xlsx files and expose it to adk web using an MCP (Motive Conversation Protocol) server. This ensures your solution works for both command-line and web interfaces.

---

Hello! That's an excellent question. Your approach of using a tool to handle file types not natively supported by Gemini is on the right track. The challenge, as you've noted, is making that tool available to the adk web environment, which runs as a separate process.

The recommended way to bridge this gap is by exposing your custom tool through an MCP server. Here’s a breakdown of the approach:

1. Create a Custom Function Tool

First, you would create a standard Python function to do the work and wrap it in an ADK FunctionTool. This tool would be responsible for reading the .xlsx file and returning its content, likely in a JSON format that the agent can easily process.

For example, you could have a tool that uses a library like pandas to read the Excel file:

# your_tools/excel_reader.py
import pandas as pd
from google.adk.tools import FunctionTool

def read_excel_file(file_path: str) -> str:
    """Reads an Excel file and returns its content as a JSON string."""
    try:
        df = pd.read_excel(file_path)
        return df.to_json(orient='records')
    except Exception as e:
        return f"Error reading Excel file: {e}"

excel_reader_tool = FunctionTool(
    fn=read_excel_file,
    description="Reads the content of an .xlsx file given a file path."
)

2. Expose the Tool via an MCP Server

To make this tool accessible to adk web, you need to run it within an MCP server. This server acts as a microservice that listens for tool calls from your agent. ADK provides utilities to make this straightforward. [1]

You would create a server script that imports your tool and serves it. Here is a simplified example based on the official documentation:

# my_mcp_server.py
import asyncio
from mcp.server.lowlevel import Server
import mcp.server.stdio
from google.adk.tools.mcp_tool.conversion_utils import adk_to_mcp_tool_type

# Import your custom tool
from your_tools.excel_reader import excel_reader_tool

# ... (server setup code from documentation) ...

async def execute_tool(name, params, context):
    if name == excel_reader_tool.name:
        # Logic to call your tool
        # ...

# ... (server runner code) ...

3. Running Your Solution

• For adk web: You would start your MCP server as a separate process. Then, when you run adk web, your agent can be configured to communicate with this server to use the excel_reader_tool.
• For command-line (adk run): Your command-line workflow can be configured to directly use the tool or communicate with the MCP server, providing a unified solution.

Handling Files with Artifacts

For managing the files themselves (like user uploads), you should leverage ADK Artifacts. [7] Artifacts are designed for handling binary data and large files, allowing you to save, load, and pass file references to your tools in a structured way.

By combining a custom FunctionTool, an MCP server, and ADK Artifacts, you can build a robust solution for handling any file type that works consistently across both local command-line execution and the adk web interface.

[1] mcp-tools.html
[7] artifacts/index.html