AgentEngineSandboxCodeExecutor causing Malformed Function Call (with workaround)

[SalvitSimmus7]

Context & Issue

I attempted to integrate the AgentEngineSandboxCodeExecutor into my Google ADK LLM agent for code execution, following the official example and documentation. My setup included passing the sandbox resource name to the agent's code_executor parameter, like so:

from google.adk.code_executors.agent_engine_sandbox_code_executor import AgentEngineSandboxCodeExecutor

# ... inside Agent initialization:
agent = Agent(
    model="gemini-2.5-pro", 
    name="my_agent",
    instruction="...",  # instructions omitted for brevity
    **# Dev note: this doesn't work – always errors out**
    # code_executor=AgentEngineSandboxCodeExecutor(
    #     sandbox_resource_name=sandbox_resource_name
    # ),
    tools=tools_list,  # (added my other tools here)
    ...
)

Despite using the latest ADK version and following the official sample code, docs and even specific agent instructions (here and here), the agent consistently failed whenever it tried to execute code. The error was MALFORMED_FUNCTION_CALL, indicating the function call format from the model was not accepted. For example, the agent’s event would result in an error like:

error_code='MALFORMED_FUNCTION_CALL'  
error_message="Malformed function call: print(default_api.append_analysis(template_json={...}, text='To provide further context...'))

In other words, instead of properly invoking the code execution, the model output got misinterpreted as an invalid function call. It seems the LLM wasn’t calling the sandbox executor correctly (possibly printing the function call or otherwise formatting it incorrectly), causing ADK to flag it as malformed. Adjusting instructions didn’t resolve this – the agent never successfully executed code via the built-in AgentEngineSandboxCodeExecutor tool.

Workaround Implementation

To unblock development, I implemented a custom code execution tool as a workaround. Instead of relying on code_executor=AgentEngineSandboxCodeExecutor(...), I created a function that calls the Vertex AI Agent Engine sandbox directly via the Python client, and I exposed this function to the agent as a standard FunctionTool. Essentially, the agent now calls this tool with the code as a string.

Key parts of the workaround:

• Custom execute_code function: Uses the Vertex AI client to execute code in the sandbox and returns the output.
• Agent tools configuration: Include this execute_code function as a tool in the agent’s tool list (instead of using the code_executor parameter).

Here’s a simplified version of the execute_code tool implementation:

from google.adk.tools import FunctionTool

def execute_code(code: str) -> dict:
    """Execute Python code in the Agent Engine sandbox and return the result or error."""
    sandbox_name = sm.get_client_sandbox()
    input_data = { "code": code }
    try:
        response = sm.client.agent_engines.sandboxes.execute_code(
            name=sandbox_name,
            input_data=input_data
        )
        # Process response.outputs to extract printed output or any returned data
        outputs = []
        for chunk in response.outputs:
            outputs.append({
                "mime_type": chunk.mime_type,
                "data": chunk.data.decode('utf-8') if chunk.data else None
            })
        return { "status": "success", "outputs": outputs }
    except Exception as e:
        return { "status": "error", "message": str(e) }

# Register the function as a tool for the agent
my_tools = [
    FunctionTool(rag_search),
    FunctionTool(execute_code),   # Custom code execution tool
    FunctionTool(load_data_source),
    # ... other tools ...
]

agent = Agent(
    model="gemini-2.5-pro",
    name="my_agent",
    instruction=agent_instructions,
    tools=my_tools,
    # code_executor=AgentEngineSandboxCodeExecutor(...)  # (not used due to issues)
)

With this setup, the LLM can call execute_code as a tool, passing the code to execute as an argument (a string). Internally, this function uses client.agent_engines.sandboxes.execute_code(...) to run the code in the sandbox and captures the output. For this to work, you need to be pretty insistent in the agent's static instructions, showing examples of how to pass the code string to the execude_code tool. This manual tool approach has been working reliably – the agent is able to run Python code (e.g., data analysis with pandas) and get the results back.

However, this approach is essentially a custom solution. It’s more verbose and lacks the tight integration that the built-in AgentEngineSandboxCodeExecutor is supposed to provide (e.g., automatic parsing of tool_code/tool_outputs blocks, etc.).

Discussion Points / Questions

Am I doing something wrong with AgentEngineSandboxCodeExecutor?
Given that I followed the official example and documentation, I suspect this might be a bug or limitation in the current preview. The MALFORMED_FUNCTION_CALL errors suggest the LLM’s function-call output wasn’t handled as expected. Is there a known issue or additional step needed (such as a special system instruction or formatting) to get the built-in code executor working?

Is this a known bug or limitation of the preview?
The code execution integration is in “preview” (as noted in the docs), so perhaps it’s not fully stable. Has anyone else experienced similar issues using code_executor=AgentEngineSandboxCodeExecutor? Any confirmation that this is a bug would be helpful (so I know it’s not just my setup).

Future plans for code execution in ADK:
What is the roadmap for the AgentEngineSandboxCodeExecutor tool? Are there plans to improve its reliability or make it generally available soon? The feature is extremely useful (my use case is an agent doing data analysis with Python code), and a built-in solution would be cleaner than the workaround. Knowing if upcoming ADK releases will address this would help in planning – e.g., I could stick with the workaround for now and later replace it with the official tool once it’s fixed.

Any insights or advice would be greatly appreciated! Is there something I missed in configuring the AgentEngineSandboxCodeExecutor? Or should I continue with the custom tool until the feature matures? Thank you in advance for any guidance on this issue.

[adk-bot]

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

TLDR: Your implementation of AgentEngineSandboxCodeExecutor is correct, but the MALFORMED_FUNCTION_CALL error likely stems from the model needing more specific instructions on how to use the integrated code executor. The feature is also in "Preview" and might have some instability. Providing a detailed base_system_instruction should resolve the issue.

---

Hello! Thank you for the incredibly detailed report and for sharing your clever workaround. This is valuable feedback for the ADK team.

Based on the official documentation, your approach to implementing the AgentEngineSandboxCodeExecutor is correct. The issue you're facing isn't with your code structure but likely with the instructions provided to the LLM.

1. The Importance of System Instructions for Code Execution

When using the integrated code_executor, the model needs very specific guidance on how to format its output for code execution. The MALFORMED_FUNCTION_CALL error suggests the model is attempting to call a standard tool instead of executing code within the sandbox.

The official documentation provides an advanced example with a base_system_instruction designed to prevent this exact problem. It guides the model to use special formatting for Python code and print() for displaying outputs, which the AgentEngineSandboxCodeExecutor is designed to handle.

Here is an example instruction from the documentation that you should try adding to your agent's configuration. [1]

# Recommended system instructions for code execution
BASE_SYSTEM_INSTRUCTION = """
You are a helpful agent that can write and execute Python code to answer user questions.

You have access to a sandboxed Python environment for code execution.
The environment is stateful, so you can declare variables and functions in one turn and use them in the next.
Any print() statements will be visible to you in the next turn.
Do not re-initialize or re-declare variables or functions in subsequent turns.
When you need to execute Python code, use the special format provided by your tools.
"""

agent = Agent(
    model="gemini-1.5-pro",
    # ...
    code_executor=AgentEngineSandboxCodeExecutor(
        sandbox_resource_name="your_sandbox_name"
    ),
    base_system_instruction=BASE_SYSTEM_INSTRUCTION,
    # ...
)

By providing these explicit instructions, the agent should correctly distinguish between calling a standard tool and executing code, resolving the error.

2. "Preview" Feature Status

As you noted, the documentation confirms that the Agent Engine Code Execution feature is a Preview release. [1] This means that while it's a powerful feature, there might be some limitations or unexpected behavior. Your experience is a perfect example of the kind of feedback that helps improve the tool during this phase.

3. Future Plans and Your Workaround

Your workaround of creating a custom FunctionTool is an excellent and recommended approach for unblocking development when a built-in feature doesn't meet your needs.

While there is no public roadmap, the introduction of AgentEngineSandboxCodeExecutor as a major feature suggests it is a key part of the vision for ADK. It offers benefits like persistent state and better isolation that a custom tool can't easily replicate. It is likely to become more stable and reliable in future releases.

For now, our recommendation is:

• Try implementing the base_system_instruction as shown above. This is the most likely fix.
• If you still face issues, continue using your reliable workaround and keep an eye on the ADK release notes for updates on the code execution feature.

We appreciate you bringing this to our attention.

---

[1] https://google.github.io/adk-docs/tools/google-cloud/code-exec-agent-engine/