Mixed Frontend and Backend Tool Execution fails with OpenAI BadRequestError

[jpr5]

Migrated from archived demo repo during consolidation (PR #3418).

Original issue: CopilotKit/with-langgraph-python#3

Description:
Mixed frontend and backend tool execution fails with OpenAI BadRequestError. When both frontend and backend tools are used together in a LangGraph Python agent, the runtime produces an OpenAI BadRequestError.

---

This issue was automatically migrated from an archived demo repository.

[copilotkit-support-bot]

To resolve the OpenAI BadRequestError when mixing frontend and backend tools in a LangGraph Python agent, you need to ensure that the agent correctly handles the message history and does not attempt to send "unresolved" tool calls back to OpenAI.

OpenAI's API requires that every tool_call in an AIMessage must have a corresponding ToolMessage in the conversation history before the next AIMessage is generated or the assistant's turn is considered complete in a subsequent request.

Details

To resolve the OpenAI BadRequestError when mixing frontend and backend tools in a LangGraph Python agent, you need to ensure that the agent correctly handles the message history and does not attempt to send "unresolved" tool calls back to OpenAI.

Root Cause

OpenAI's API requires that every tool_call in an AIMessage must have a corresponding ToolMessage in the conversation history before the next AIMessage is generated or the assistant's turn is considered complete in a subsequent request.

In CopilotKit's LangGraph integration:

1. The Middleware (CopilotKitMiddleware) intercepts tool calls.
2. If an LLM returns both a backend tool call and a frontend tool call, the middleware's after_model hook removes the frontend tool call from the AIMessage so the backend ToolNode doesn't error out trying to find a handler for it.
3. The agent continues its loop (e.g., executing the backend tool).
4. The after_agent hook eventually restores the frontend tool call to the AIMessage so it can be sent to the browser for execution.
5. The Failure: If the agent's logic triggers another LLM call (e.g., in a loop) after tool calls have been restored or while they are still "intercepted" but part of the persistent state, OpenAI receives an AIMessage with tool calls that lack corresponding ToolMessage results, triggering the BadRequestError.

Recommended Solution

1. Disable Parallel Tool Calls

The most reliable way to avoid this state inconsistency is to force the model to call tools one at a time. This ensures the backend tool is fully resolved and recorded before the LLM has a chance to suggest a frontend tool call.

In your Python agent:

# When binding tools to your model
llm_with_tools = model.bind_tools(
    tools=[...], 
    parallel_tool_calls=False # This is critical for mixed tool execution
)

2. Ensure Correct Middleware Usage

Verify that you are using the CopilotKitMiddleware which correctly handles the "interception" and "restoration" of frontend tools.

from copilotkit.langgraph import CopilotKitMiddleware
from langgraph.prebuilt import create_react_agent

# Use the middleware in your agent creation
agent = create_react_agent(
    model=llm,
    tools=backend_tools,
    middleware=[CopilotKitMiddleware()]
)

3. Filter Intercepted Tool Calls in Nodes (Advanced)

If you are building a custom graph, ensure that your "Tools" node only attempts to process tool calls that exist in your backend registry. If using the prebuilt ToolNode, it will typically ignore or fail on unknown tools. The CopilotKit middleware's after_model is designed to prevent this by stripping them out temporarily.

Implementation Checklist

• Set parallel_tool_calls=False in your bind_tools call.
• Register your agent with CopilotKitMiddleware.
• Ensure frontend tools are registered on the client-side using useCopilotAction or useFrontendTool.
• Verify your LangGraph state includes the copilotkit key if using the provided CopilotKitState type:

  from copilotkit.langgraph import CopilotKitState
  
  workflow = StateGraph(CopilotKitState)

Documentation References:

• LangGraph Integration Guide
• Frontend Tools Overview
• Common CoAgent Issues & Troubleshooting

Confidence Assessment: High. This error is a known artifact of how OpenAI validates tool call sequences when state is manipulated by middleware between turns.

---

Was this helpful?

If this solution worked for you, please click on the appropriate option below to help us improve:

✅ This was helpful | ❌ Need more help