[BUGS] Prevent NullPointerException for Gemini models with empty AIMessage content

[paxiaatucsdedu]

Problem

When using Google Gemini models with tool calling, two issues prevent the full agentic tool loop from working:

Empty content error: AIMessages with empty content (content="") cause a TransientServiceError (HTTP 500) due to a NullPointerException in the OCI backend when converting messages to Google's format.

Missing tool call IDs: Gemini returns tool calls with id: None, which causes ValidationError when creating ToolMessage objects (tool_call_id must be a non-empty string).

Issue link: #78

Solution

1. Check for empty content in AIMessages with tool calls before processing, and provide a minimal placeholder (.) to prevent null serialization. This follows the same pattern used by the Cohere provider.
2. Enhanced the existing UUID fallback logic in convert_oci_tool_call_to_langchain() to check if tool_call.id is None before using it. Previously, the code only checked if "id" existed, but didn't handle the case where the value was None.

Testing

Tested with google.gemini-2.5-flash model using AIMessage with empty content and tool calls - error is now resolved.

Model response with empty content:
content='The weather in Rome is currently sunny with a temperature of 20 degrees Celsius.' additional_kwargs={'finish_reason': 'stop'} response_metadata={'finish_reason': 'stop'} id='run--15f18f69-1e8d-465d-b996-d91e208f7d49-0'

Model response with tool_call_id is None:
content='The weather in Rome is sunny with a temperature of 22°C.' additional_kwargs={'finish_reason': 'stop', 'time_created': '2025-12-17 22:09:15.398000+00:00', 'total_tokens': 56} response_metadata={'model_id': 'google.gemini-2.5-flash', 'model_version': '1.0.0', 'request_id': 'A5559EBE7F2146A7BA83C43D3F3F15B5/9AA6710DD987FB0AD1760230AD667DDA/085E0D086FF026F6C6002D3E16462892', 'content-length': '304', 'finish_reason': 'stop', 'time_created': '2025-12-17 22:09:15.398000+00:00', 'total_tokens': 56} id='run--1936f4a2-24d3-4d91-afd3-37c4f1153e6a-0'

[paxiaatucsdedu]

@luigisaetta Does this resolve your issue?

[YouNeedCryDear]

so there has to be an arbitrary character in the the text?

[paxiaatucsdedu]

Yes, I tried to use an empty space as the content, but empty space does not work.

[luigisaetta]

Should this PR be merged with: #81?
They seems to address similar issues (support for Gemini calls with tools)?

[paxiaatucsdedu]

Should this PR be merged with: #81? They seems to address similar issues (support for Gemini calls with tools)?

Gemini tool calls work with non-empty content field.

[fede-kamel]

Hey @paxiaatucsdedu, thanks for working on this fix! I wanted to share some test results that might be helpful.

I ran integration tests to check the full tool calling flow with Gemini, and found that the empty content fix alone may not be enough for the complete agentic loop.

Test Evidence

Test 1: GenericProvider (current approach) - FAILS

============================================================
Testing GenericProvider with google.gemini-2.5-flash
============================================================

Step 1: Getting tool calls from Gemini...
Response: tool_calls=[{'name': 'get_weather', 'args': {'city': 'Rome'}, 'id': None, 'type': 'tool_call'}]
Tool calls: [{'name': 'get_weather', 'args': {'city': 'Rome'}, 'id': None, 'type': 'tool_call'}]

Step 2: Sending tool result back to Gemini...
Messages being sent: ['HumanMessage', 'AIMessage', 'ToolMessage']

Expected failure after 0.0s:
Error type: ServiceError
Error: {'status': 400, 'message': "Missing required parameter: 'messages[1].toolCalls[0].id'."}

✓ Confirmed: GenericProvider fails for Gemini tool loop
   Root cause: OCI cannot properly handle tool messages for Gemini models
PASSED

Test 2: GeminiProvider (PR #81 approach) - SUCCEEDS

============================================================
Testing GeminiProvider with google.gemini-2.5-flash
============================================================

Step 1: Getting tool calls from Gemini...
Response: tool_calls=[{'name': 'get_weather', 'args': {'city': 'Rome'}, 'id': None, 'type': 'tool_call'}]
Tool calls: [{'name': 'get_weather', 'args': {'city': 'Rome'}, 'id': None, 'type': 'tool_call'}]

Step 2: Sending tool result back to Gemini...
Messages being sent: ['HumanMessage', 'AIMessage', 'ToolMessage']

Success after 0.7s!
Final response: The weather in Rome is sunny, 22°C.

✓ Confirmed: GeminiProvider works for Gemini tool loop
PASSED

======================== 2 passed in 3.98s ========================

Issues Found

1. Gemini returns tool calls with id: None (no tool_call_id)
2. The ToolMessage type doesn't translate correctly to Gemini's native format
3. The AssistantMessage.tool_calls field causes issues with OCI's Gemini translation

Suggestion

In PR #81, I worked around these OCI translation limitations by converting tool-related messages to regular user/assistant messages. This has 38 passing integration tests including real agent workflows.

Would it make sense to combine our efforts? Happy to discuss!

[paxiaatucsdedu]

Hi @fede-kamel, thank you for testing it. I tested with the test python script from this issue description. Gemini works with no problem as long as the content is not empty, and the Gemini model response is very similar to the grok-4 model (Grok-4 is mentioned in the issue description as working properly).

This is the Jupyter notebook I used for testing with PR #79
issue_78.ipynb

[fede-kamel]

Here's the minimal test code to reproduce:

from langchain_core.messages import HumanMessage, ToolMessage
from langchain_core.tools import tool
from langchain_oci.chat_models import ChatOCIGenAI

@tool
def get_weather(city: str) -> str:
    """Get weather for a city."""
    return f"Sunny, 22°C in {city}"

# Create LLM with tools
llm = ChatOCIGenAI(model_id="google.gemini-2.5-flash", ...)
llm_with_tools = llm.bind_tools([get_weather])

# Step 1: Get tool calls (works)
messages = [HumanMessage(content="What's the weather in Rome?")]
response = llm_with_tools.invoke(messages)
# Returns: tool_calls=[{'name': 'get_weather', 'args': {'city': 'Rome'}, 'id': None}]

# Step 2: Send tool result back (fails)
messages.append(response)
messages.append(ToolMessage(
    content="Sunny, 22°C in Rome",
    tool_call_id="call_get_weather",  # Note: Gemini returned id=None
    name="get_weather",
))
final = llm_with_tools.invoke(messages)  # 💥 400 error

The error occurs because OCI can't translate ToolMessage + AIMessage.tool_calls for Gemini models.

[fede-kamel]

Hi @paxiaatucsdedu! Thanks for sharing the notebook - it helped me understand your test setup better.

I did some additional testing and found something interesting. The notebook test works because it uses a manually constructed conversation history with a hardcoded tool_call_id:

# From notebook - REQUEST 2
AIMessage(content="", tool_calls=[{"id": "call_ed2635c686f449eea25915b2", ...}])
ToolMessage(content="<tool_response!>", tool_call_id="call_ed2635c686f449eea25915b2")

However, when I tested the real agentic flow (asking Gemini, getting its response, executing tool, sending result back), I found that Gemini actually returns id: None:

[STEP 1] User asks: 'What is the weather in Rome?'

Gemini response:
  tool_calls: [{'name': 'get_weather', 'args': {'city': 'Rome'}, 'id': None}]
                                                                  ^^^^^^^^
                                                                  Gemini returns None!

[STEP 2] Execute tool → Result: 'Sunny, 22°C in Rome'

[STEP 3] Send tool result back to Gemini...
  ⚠️ Problem: tool_call_id is None!

[RESULT] ✗ FAILED
  Error: "Missing required parameter 'toolCalls[0].id'"

So the issue is:

Scenario	tool_call_id	Result
Notebook (hardcoded)	"call_ed2635..."	✅ Works
Real Gemini response	None	❌ Fails

Your empty content fix is valid and needed (Test 1→2 in my earlier tests), but there's this additional id: None issue that also needs to be addressed for the full agentic loop to work.

Happy to share the test script if you'd like to reproduce this on your end!

[fede-kamel]

And just to show how PR #81 addresses this - the GeminiProvider works around these OCI translation limitations by converting tool messages to regular messages:

# Instead of sending ToolMessage (which OCI can't translate for Gemini)
# GeminiProvider converts it to a UserMessage:

ToolMessage(content="Sunny, 22°C") 
    → UserMessage(content="Function get_weather returned: Sunny, 22°C")

# And AIMessage with tool_calls (where id=None is a problem)
# becomes a regular AssistantMessage:

AIMessage(content="", tool_calls=[{id: None, name: "get_weather", ...}])
    → AssistantMessage(content="I'll call get_weather with arguments: {\"city\": \"Rome\"}")

This bypasses both issues:

1. ✅ No empty content problem (converted to descriptive text)
2. ✅ No id: None problem (tool_calls field is not sent to OCI)

Same test with GeminiProvider:

[STEP 1] Gemini returns tool_calls with id=None ← same as before
[STEP 2] Execute tool ← same as before  
[STEP 3] Send result back → ✅ Success!
         Final response: "The weather in Rome is sunny, 22°C."

Both PRs could work together - your fix handles the empty content edge case, and the GeminiProvider handles the message format translation. What do you think?

[paxiaatucsdedu]

Thanks @fede-kamel for the thorough testing and catching the id=None issue — that's a real gap in the full tool loop.

However, we already have UUID generation logic in convert_oci_tool_call_to_langchain(). The issue is that the current code on main only checks if the id exists, but doesn't handle the case where tool_call.id is None:

Current (main):

id=tool_call.id if "id" in tool_call.attribute_map else uuid.uuid4().hex
When Gemini returns "id": null, this evaluates to id=None ✗

My fix:

if "id" in tool_call.attribute_map and tool_call.id:
    id = tool_call.id
else:
    id = uuid.uuid4().hex

Now when tool_call.id is None, we generate a UUID ✓

This is a 3-line change that makes the existing UUID fallback logic work correctly for Gemini. No need for a separate provider or message rewriting layer — we just needed to check for null/empty IDs before using them.

Your GeminiProvider approach is clever, and it clearly works, but I’m a bit concerned it adds complexity and may have edge cases. If a small fix can make OCI accept the canonical tool message format for Gemini, I’d prefer that direction because it’s simpler to maintain and more aligned with how other providers behave.

Thanks again for the detailed testing!

[fede-kamel]

Thanks for working on this fix! I tested locally and can confirm this solution works for the Gemini tool calling flow.

Test Results:

• ✅ Full agentic loop completes successfully (tool call → execution → ToolMessage → final response)
• ✅ UUID generation correctly handles Gemini's id: None
• ✅ Empty content fix prevents NullPointerException
• ✅ Both gemini-2.5-flash and gemini-2.5-pro models work
• ✅ All integration tests pass (6/6 passed in 11.80s)

The GenericProvider approach with your fixes appears to be sufficient for the time being. The simple 13-line fix is preferable to a more complex provider workaround.

cc: @luigisaetta - this should resolve your issue!

Thanks to the team for the quick turnaround on this! 🙏