Pass Custom Parameters to /sse

[sandeep540]

** Please make sure you read the contribution guide and file the issues in the right place. **
Contribution guide.

Is your feature request related to a problem? Please describe.
I want to pass some custom params to /SSE endpoint may be in Body (or) headers, I havent seen any place where I can do it? I need to pass params like tenant/facility/role, how can I pass and consume the same?

Describe the solution you'd like
NA

Describe alternatives you've considered
Over-riding the codebase

Additional context

[hangfei]

@adk-bot

[adk-bot]

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

TLDR: You can pass your custom parameters (tenant, facility, role) in the JSON body of your POST request to the /run_sse endpoint by including them in the state_delta field. This avoids the need to override the codebase.

---

Hello! I can help with your question about passing custom parameters to the Server-Sent Events (SSE) endpoint.

While the default /run_sse endpoint in ADK doesn't directly support arbitrary custom headers or query parameters for this purpose, it provides a structured way to pass contextual data through the request body using the state_delta field. This field is part of the RunAgentRequest and allows you to merge data into the session state at the beginning of a run. [cite: 4, 11]

Here is how you can do it:

1. Send Parameters in the Request Body

When you make a POST request to /run_sse, include your custom parameters within the state_delta object in the JSON body.

Example POST /run_sse request body:

{
  "app_name": "your_app_name",
  "new_message": "your user message",
  "state_delta": {
    "tenant": "your-tenant-id",
    "facility": "your-facility-id",
    "role": "your-user-role"
  }
}

2. Access Parameters in Your Tools

The data from state_delta will be merged into the session's state. You can then access these values from within any of your custom tools by using the ToolContext object. [cite: 6]

Example my_tool.py:

from google.adk.tools import Tool, ToolContext

class MyTool(Tool):
  def run(self, params: dict, tool_context: ToolContext) -> str:
    # Access your custom parameters from the session state
    tenant = tool_context.state.get("tenant")
    facility = tool_context.state.get("facility")
    role = tool_context.state.get("role")

    # Now you can use these values in your tool's logic
    print(f"Executing tool for tenant: {tenant} in facility: {facility} with role: {role}")
    
    return "Tool executed with custom context."

This approach allows you to pass and consume your parameters without needing to modify the core ADK codebase.

For more advanced scenarios that might require custom logic beyond passing data, you could consider creating a new FastAPI endpoint and adding it to the app object, as suggested in the ADK documentation. [cite: 1, 2] However, for your described use case, using state_delta is the most direct and idiomatic solution.

I hope this helps!

---

[1] https://github.com/google/adk-python/blob/main/contributing/adk_project_overview_and_architecture.md
[2] https://google.github.io/adk-docs/streaming/custom-streaming/
[4] https://google.github.io/adk-docs/api-reference/rest/
[6] https://google.github.io/adk-docs/tools-custom/
[11] https://github.com/google/adk-python/blob/main/src/google/adk/cli/adk_web_server.py

[adk-bot]

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

TLDR: You can pass custom parameters to the /sse endpoint by appending them as query parameters to the connection URL on the client-side and then updating your server-side FastAPI endpoint to receive them.

---

Hello! Based on the information in the ADK documentation, here is a way you can achieve your goal of passing custom parameters to the SSE endpoint.

Using Query Parameters

The most direct method is to add your custom parameters as query strings to the SSE endpoint URL. The ADK's documentation provides an example of this with the is_audio parameter. [cite: 1]

1. Client-Side (JavaScript)

In your client-side code where you establish the EventSource connection, you can append your custom parameters to the URL:

// Existing parameters
const sessionId = Math.random().toString().substring(10);
let is_audio = false;

// Your custom parameters
const tenant = "my-tenant";
const facility = "main-facility";
const role = "admin";

// Construct the URL with all parameters
const sse_url = `http://${window.location.host}/events/${sessionId}?is_audio=${is_audio}&tenant=${tenant}&facility=${facility}&role=${role}`;

const eventSource = new EventSource(sse_url);

// ... rest of your EventSource handlers

2. Server-Side (Python/FastAPI)

Next, you need to update the signature of your /events/{user_id} endpoint in your Python application to accept these new query parameters. FastAPI will automatically parse them from the URL.

Here is an example of how you can modify your endpoint: [cite: 1]

from fastapi import FastAPI

app = FastAPI()

# ... other code

@app.get("/events/{user_id}")
async def sse_endpoint(
    user_id: int,
    is_audio: str = "false",
    tenant: str = None,      # Add your custom param
    facility: str = None,    # Add your custom param
    role: str = None         # Add your custom param
):
    """SSE endpoint for agent to client communication"""
    print(f"SSE connection received for user {user_id} with the following params:")
    print(f"  - Tenant: {tenant}")
    print(f"  - Facility: {facility}")
    print(f"  - Role: {role}")

    # You can now use these variables in your session handling or agent logic
    # For example:
    # live_events, live_request_queue = await start_agent_session(
    #     user_id_str,
    #     is_audio == "true",
    #     custom_context={"tenant": tenant, "facility": facility, "role": role}
    # )

    # ... rest of your endpoint logic

This approach is clean and leverages the existing pattern shown in the ADK documentation for passing data on connection startup.

Alternative: Using Headers

While not explicitly shown for the main SSE endpoint in the introductory examples, ADK does utilize headers for SSE connections in other areas, such as for MCP tools. [cite: 6, 10] You could potentially send custom headers from your client and use FastAPI's Request object on the server to read them. However, the query parameter approach is more straightforward and is already demonstrated in the context of the /events endpoint. [cite: 1]

I hope this helps you implement the functionality you're looking for!