🐛 Bug: AG-UI ADK Auth crashes: Object of type SecuritySchemeType is not JSON serializable

[rcleveng]

♻️ Reproduction Steps

If you try to enable Auth for any ADK action, then AG-UI's middleware throws an exception.

See google/adk-python#3288 - but this is on the AG-UI middleware.

Any ideas what a fix would look like?

✅ Expected Behavior

I expect it to not crash

❌ Actual Behavior

It crashed

𝌚 CopilotKit Version

@copilotkit/react-core 1.10.6
@copilotkit/react-ui 1.10.6
@copilotkit/runtime 1.10.6

📄 Logs (Optional)

2025-11-16 06:59:00,588 - ag_ui_adk.adk_agent - ERROR - Background execution error: Object of type SecuritySchemeType is not JSON serializable
Traceback (most recent call last):
  File "/Users/r/git/lairo/app-be/backend/agent_api/.venv/lib/python3.14/site-packages/ag_ui_adk/adk_agent.py", line 1102, in _run_adk_in_background
    async for ag_ui_event in event_translator.translate_lro_function_calls(
    ...<5 lines>...
        logger.debug(f"Event queued: {type(ag_ui_event).__name__} (thread {input.thread_id}, queue size after: {event_queue.qsize()})")
  File "/Users/r/git/lairo/app-be/backend/agent_api/.venv/lib/python3.14/site-packages/ag_ui_adk/event_translator.py", line 443, in translate_lro_function_calls
    args_str = json.dumps(long_running_function_call.args) if isinstance(long_running_function_call.args, dict) else str(long_running_function_call.args)
               ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/r/.local/share/uv/python/cpython-3.14.0-macos-aarch64-none/lib/python3.14/json/__init__.py", line 231, in dumps
    return _default_encoder.encode(obj)
           ~~~~~~~~~~~~~~~~~~~~~~~^^^^^
  File "/Users/r/.local/share/uv/python/cpython-3.14.0-macos-aarch64-none/lib/python3.14/json/encoder.py", line 200, in encode
    chunks = self.iterencode(o, _one_shot=True)
  File "/Users/r/.local/share/uv/python/cpython-3.14.0-macos-aarch64-none/lib/python3.14/json/encoder.py", line 261, in iterencode
    return _iterencode(o, 0)
  File "/Users/r/.local/share/uv/python/cpython-3.14.0-macos-aarch64-none/lib/python3.14/json/encoder.py", line 180, in default
    raise TypeError(f'Object of type {o.__class__.__name__} '
                    f'is not JSON serializable')
TypeError: Object of type SecuritySchemeType is not JSON serializable
when serializing dict item 'type'
when serializing dict item 'authScheme'
when serializing dict item 'authConfig'
2025-11-16 06:59:00,590 - google_adk.google.adk.runners - INFO - Closing toolset: ClientProxyToolset
2025-11-16 06:59:00,590 - ag_ui_adk.client_proxy_toolset - INFO - Closing ClientProxyToolset
2025-11-16 06:59:00,590 - google_adk.google.adk.runners - INFO - Successfully closed toolset: ClientProxyToolset
2025-11-16 06:59:00,596 - ag_ui_adk.session_manager - INFO - Updated state for session Project Apprentice:9cda2234-ffac-4d55-b834-13e1cf4d8b09
2025-11-16 06:59:00,596 - ag_ui_adk.adk_agent - INFO - Added tool call adk-d05dd57e-cccd-4e76-a6ce-b4114cfd5bb2 to session 9cda2234-ffac-4d55-b834-13e1cf4d8b09 pending list
2025-11-16 06:59:00,599 - ag_ui_adk.adk_agent - INFO - Preserving execution for thread 9cda2234-ffac-4d55-b834-13e1cf4d8b09 - has pending tool calls (HITL scenario)
2025-11-16 06:59:00,599 - opentelemetry.context - ERROR - Failed to detach context
Traceback (most recent call last):
  File "/Users/r/git/lairo/app-be/backend/agent_api/.venv/lib/python3.14/site-packages/opentelemetry/trace/__init__.py", line 589, in use_span
    yield span
  File "/Users/r/git/lairo/app-be/backend/agent_api/.venv/lib/python3.14/site-packages/opentelemetry/sdk/trace/__init__.py", line 1105, in start_as_current_span
    yield span
  File "/Users/r/git/lairo/app-be/backend/agent_api/.venv/lib/python3.14/site-packages/opentelemetry/trace/__init__.py", line 454, in start_as_current_span
    yield span
  File "/Users/r/git/lairo/app-be/backend/agent_api/.venv/lib/python3.14/site-packages/google/adk/flows/llm_flows/base_llm_flow.py", line 801, in _call_llm_with_tracing
    yield llm_response
GeneratorExit

[copilotkit-support-bot]

The error occurs because the SecuritySchemeType object used in ADK Auth is not directly JSON serializable. This is a common issue when trying to serialize complex objects or enums in Python, especially in the context of ADK integration.

Details

Root Cause

The 'Object of type SecuritySchemeType is not JSON serializable' error occurs because:

• Complex Object Serialization: The SecuritySchemeType from the ag_ui_adk package is a complex enum or object that cannot be directly JSON serialized
• ADK Integration Layer: This happens when ADK authentication objects are being serialized during the integration process between CopilotKit and Google's Agent Development Kit
• Similar Pattern: This is the same type of serialization issue found with other complex objects like Message and ChatCompletionMessageToolCall in the codebase

Solution Pattern

The codebase already contains a proven solution pattern for handling complex object serialization. Here's what the fix would look like:

1. Create Auth Serialization Handler

def prepare_auth_for_serialization(auth_obj):
    """
    Recursively prepare authentication objects for JSON serialization.
    Similar to prepare_state_for_serialization pattern found in coagents examples.
    """
    if isinstance(auth_obj, dict):
        return {k: prepare_auth_for_serialization(v) for k, v in auth_obj.items()}
    elif isinstance(auth_obj, list):
        return [prepare_auth_for_serialization(item) for item in auth_obj]
    elif hasattr(auth_obj, 'model_dump'):  # Pydantic models
        return auth_obj.model_dump()
    elif hasattr(auth_obj, 'to_dict'):
        return auth_obj.to_dict()
    elif hasattr(auth_obj, '__dict__'):
        return prepare_auth_for_serialization(auth_obj.__dict__)
    else:
        try:
            return vars(auth_obj)
        except TypeError:
            return str(auth_obj)  # Fallback to string representation

2. Custom JSON Encoder Approach

import json
from ag_ui_adk import SecuritySchemeType  # Import the problematic type

class ADKAuthEncoder(json.JSONEncoder):
    """Custom JSON encoder for ADK authentication objects."""
    
    def default(self, obj):
        if isinstance(obj, SecuritySchemeType):
            # Convert SecuritySchemeType to serializable format
            if hasattr(obj, 'value'):
                return obj.value
            elif hasattr(obj, '__dict__'):
                return obj.__dict__
            else:
                return str(obj)
        return super().default(obj)

# Usage in ADK integration code
json.dumps(auth_data, cls=ADKAuthEncoder)

3. Apply Fix in ADK Integration Points

The fix should be applied wherever ADK authentication objects are being serialized, particularly:

• ADKAgent authentication setup
• add_adk_fastapi_endpoint auth handling
• Any auth state emissions or API calls

Implementation Examples

Scenario 1: State Emission Fix

# Before (causes error)
copilotkit_emit_state(auth_config)

# After (fixed)
serialized_auth = prepare_auth_for_serialization(auth_config)
copilotkit_emit_state(serialized_auth)

Scenario 2: API Response Fix

# Before (causes error)
return {"auth": security_scheme_object}

# After (fixed)
return {"auth": prepare_auth_for_serialization(security_scheme_object)}

Documentation References

• ADK Quickstart - Basic ADK setup
• ADK Frontend Actions - Action configuration

Source Code Examples:
• Serialization Patterns - Complete serialization handling examples
• Coagents Starter - MessageEncoder implementation

The solution follows the established patterns in the CopilotKit codebase for handling complex object serialization, ensuring ADK authentication objects are properly converted to JSON-serializable formats.

---

Was this helpful?

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

✅ Issue Solved | ❌ Need more help

[copilotkit-support-bot]

The error occurs because FastAPI's security scheme objects (like SecuritySchemeType) are not JSON serializable, and CopilotKit's AG-UI middleware tries to serialize them when authentication is enabled for ADK actions. To fix this, you should extract only the necessary, JSON-serializable authentication data and avoid passing FastAPI security objects into CopilotKit's serialization pipeline.

Details

Root Cause

The error occurs because FastAPI's security objects (like HTTPBearer, HTTPBasic, etc.) are not JSON serializable by default. When you enable authentication for ADK actions, these FastAPI security scheme objects get passed through CopilotKit's JSON serialization pipeline, which requires all objects to be JSON serializable for the AG-UI protocol.

• SecuritySchemeType comes from FastAPI's security module - not from CopilotKit itself
• ADK uses FastAPI integration pattern - add_adk_fastapi_endpoint function consistently used across all examples
• CopilotKit requires JSON serialization - AG-UI protocol demands all state and objects be JSON serializable
• Conflict occurs during serialization - FastAPI security objects hit json.dumps/JSON.stringify calls and fail

Solutions

Solution 1: Extract Authentication Data Instead of Passing Security Objects

Instead of passing the entire FastAPI security object, extract only the necessary authentication data:

from fastapi import Depends, HTTPException
from fastapi.security import HTTPBearer
from ag_ui_adk import ADKAgent, add_adk_fastapi_endpoint

security = HTTPBearer()

async def get_current_user(token: str = Depends(security)):
    # Validate token and return user data
    # Return only JSON-serializable data
    return {
        "user_id": "user123",
        "email": "user@example.com",
        "permissions": ["read", "write"]
    }

# Use the extracted user data in your ADK actions
async def my_authenticated_action(user_data: dict = Depends(get_current_user)):
    # user_data is JSON serializable
    return {"result": f"Action performed by {user_data['email']}"}

Solution 2: Implement Custom Serialization for Auth Context

Create a custom authentication context that's JSON serializable:

from pydantic import BaseModel
from typing import Optional

class AuthContext(BaseModel):
    user_id: str
    token: Optional[str] = None
    permissions: list[str] = []
    
    class Config:
        # Ensures Pydantic model is JSON serializable
        json_encoders = {
            # Add any custom encoders if needed
        }

async def get_auth_context(token: str = Depends(security)) -> AuthContext:
    # Validate token and create serializable context
    return AuthContext(
        user_id="user123",
        permissions=["read", "write"]
    )

Solution 3: Separate Auth Validation from State Management

Keep authentication separate from the serializable state:

from ag_ui_adk import ADKAgent, add_adk_fastapi_endpoint

# Separate auth validation
async def validate_auth(token: str = Depends(security)):
    # Just validate, don't return the security object
    if not token:
        raise HTTPException(status_code=401, detail="Unauthorized")
    return True

# Use in ADK actions without passing security objects
async def my_action(validated: bool = Depends(validate_auth)):
    # Only JSON-serializable data in the action
    action_data = {
        "action": "performed",
        "timestamp": "2024-01-01T00:00:00Z",
        "authenticated": validated
    }
    return action_data

Implementation Pattern

Here's the recommended pattern for ADK with authentication:

from fastapi import FastAPI, Depends, HTTPException
from fastapi.security import HTTPBearer
from ag_ui_adk import ADKAgent, add_adk_fastapi_endpoint

app = FastAPI()
security = HTTPBearer()

# Auth validation (no serialization involved)
async def verify_token(token: str = Depends(security)) -> str:
    # Validate and return only the user identifier
    if not token or token != "valid_token":
        raise HTTPException(status_code=401, detail="Invalid token")
    return "user123"  # Return JSON-serializable user ID

# ADK integration with serializable auth data
agent = ADKAgent(
    name="authenticated_agent",
    description="Agent with authentication",
)

@agent.action()
async def authenticated_action(user_id: str = Depends(verify_token)):
    # All data here is JSON serializable
    return {
        "message": f"Action performed by user {user_id}",
        "success": True
    }

# Add to FastAPI without security object serialization issues
add_adk_fastapi_endpoint(app, agent, "/copilotkit")

Key Principles

• Never pass FastAPI security objects directly to CopilotKit serialization
• Extract only necessary auth data as JSON-serializable types (strings, dicts, lists)
• Use Pydantic models for complex auth contexts to ensure JSON compatibility
• Separate validation from state - validate auth but don't serialize security objects

The error occurs specifically at the boundary between FastAPI's security system and CopilotKit's serialization requirements. Following these patterns will resolve the JSON serialization error while maintaining proper authentication.

Documentation References:

• ADK Quickstart - Basic ADK integration patterns

---

Was this helpful?

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

✅ Issue Solved | ❌ Need more help

[copilotkit-support-bot]

👋 Thanks for your feedback!

I've escalated this issue to our development team. Someone from our team will review your request and provide additional assistance shortly.

If this is blocking production, please book a meeting with us at https://cal.com/nathan-tarbert-copilotkit/15min