How to pass custom HTTP headers (e.g. Authorization) from /run request into ADK tools?

[DonaldJacamoTP]

How to pass custom HTTP headers (e.g. Authorization) from /run request into ADK tools?

Hi 👋

I’m building a Google ADK project where an agent calls external APIs via tools.
Each API request must be authenticated per user, using a session token (JWT / Bearer token).

This project is intended to support many concurrent users (multi-tenant), where each user can only access their own data.

---

Current setup

• I am using Google ADK with the built-in web server (adk web)
• The /run endpoint is implemented inside the ADK package (adk_web_server.py)
• Clients can send custom HTTP headers (e.g. Authorization) to /run
• Tools are used by the agent to call external APIs

---

Example request

curl http://localhost:8000/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer USER_TOKEN" \
  -d '{
    "appName": "traderpal_agent",
    "userId": "u_123",
    "sessionId": "s_123",
    "newMessage": {
      "role": "user",
      "parts": [
        { "text": "Get my account details" }
      ]
    }
  }'

---

What I want to achieve

For each /run request:

1. The client sends a user-specific token in an HTTP header (e.g. Authorization: Bearer <token>)
2. ADK receives the request
3. That token is made available inside:
   • the agent context and/or
   • the tools
4. Tools can then call authenticated APIs on behalf of that user

This token should be request-scoped, not global.

---

What I want to avoid

• ❌ Storing user tokens in environment variables
• ❌ Global or shared state across users
• ❌ Forking or monkey-patching adk_web_server.py
• ❌ One token shared across all users

---

Questions

1. Is there an official way to:

   • Access HTTP request headers from /run inside ADK?
   • Inject request-scoped metadata (like auth tokens) into the agent context or tools?

2. Is wrapping ADK with a custom FastAPI / middleware layer the recommended approach for:

   • authentication
   • session handling
   • multi-tenant scenarios?

3. Are there any built-in hooks, callbacks, or best practices for propagating per-request context into tools?

---

Constraints / Notes

• This needs to scale to many concurrent users
• Each request must remain fully isolated
• Authentication is handled outside the agent logic itself
• The agent should remain stateless across requests

---

Any guidance, best practices, or confirmation of the intended architecture would be greatly appreciated.
Thanks in advance!

[adk-bot]

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

TLDR: The recommended approach is to wrap the ADK runner in your own custom FastAPI server. This allows you to intercept the incoming request, extract the Authorization header, and inject the token into the session state before calling the ADK runner. Tools can then access this token via the ToolContext to make authenticated API calls on behalf of the user.

---

Hi @DonaldJacamoTP, thank you for the detailed question. This is a great use case for ADK's flexibility.

Here is a guide on the recommended architecture to achieve what you're looking for, which directly answers your questions.

1. Is there an official way to pass context?

Yes. The official and intended way to pass request-scoped data to your tools is through the session state. You can think of the state as a request-scoped dictionary that is accessible throughout the agent's lifecycle.

Tools access this state via the ToolContext object, which ADK automatically injects into any tool function that includes it in its signature.

from google.adk.tools import ToolContext

def my_api_tool(param: str, tool_context: ToolContext):
    # Retrieve the token from the session state
    auth_token = tool_context.state.get("user_auth_token")
    headers = {"Authorization": f"Bearer {auth_token}"}
    # ... make authenticated API call

You can find more information in the documentation on Custom Tools [1] and Context [2].

2. Is wrapping ADK in a custom server the recommended approach?

Yes, absolutely. For use cases like multi-tenancy, custom authentication, or any pre-processing of requests, wrapping ADK's core runner in your own web server is the recommended pattern. adk web is a convenient wrapper for simple cases, but ADK is designed as a library to be integrated into a larger application.

By creating your own FastAPI app, you gain full control over the request/response lifecycle.

3. What are the best practices for propagating context?

Here is the best-practice workflow:

Step 1: Create a Custom FastAPI Server

Instead of using adk web, create your own Python entrypoint (e.g., main.py). This allows you to define a custom /run endpoint where you can access the request headers.

Step 2: Intercept the Header and Inject into State

In your custom endpoint, you can access the Authorization header and inject it into the session state before the agent starts running.

from fastapi import FastAPI, Request
from google.adk.runtime import runner, get_session_manager

app = FastAPI()

@app.post("/run")
async def run_chat(request: Request, run_input: dict):
    # 1. Extract token from the header
    auth_header = request.headers.get("Authorization")
    token = auth_header.split(" ")[1] if auth_header else None

    # 2. Get the session and inject the token into its state
    session_manager = get_session_manager()
    session = await session_manager.load_session(run_input.get("sessionId"))
    session.state["user_auth_token"] = token
    
    # 3. Run the agent with the modified context
    response = await runner.run_async(
        app_name=run_input.get("appName"),
        context=session.model_dump(),
        # ... other params
    )
    return response

(This is a simplified example. See a more complete one in the Streaming Guide [4].)

Step 3: Access the Token in Your Tools

As shown in the first point, your tools can now easily access this token from tool_context.state.

Special Case: OpenAPIToolset

If you are using OpenAPIToolset, there is an even more direct mechanism using the header_provider argument. This takes a function that receives the context and returns headers, which ADK will automatically add to every API call made by that toolset.

from google.adk.tools import ToolContext
from google.adk.tools.openapi_tool import OpenAPIToolset

def get_auth_headers(context: ToolContext) -> dict:
    """Reads the token from state and constructs the auth header."""
    token = context.state.get("user_auth_token")
    if not token:
        return {}
    return {"Authorization": f"Bearer {token}"}

# When creating your toolset
my_toolset = OpenAPIToolset(
    openapi_spec=spec,
    header_provider=get_auth_headers,
)

You can see the header_provider parameter in the source code [3].

This approach ensures that your authentication logic is clean, request-scoped, and doesn't require forking any ADK components, aligning perfectly with the constraints you've outlined.

[1] https://google.github.io/adk-docs/tools-custom/
[2] https://google.github.io/adk-docs/context/
[3] https://github.com/google/adk-python/blob/main/src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py
[4] https://github.com/google/adk-docs/blob/main/examples/python/snippets/streaming/adk-streaming/app/main.py

[rohan-kavari]

I would suggest while creating a session, send the token as a payload in the body. Set the key as user:<YOUR_DESIRED_KEY>. Then you can access the key in the tool context. Set a user prefix will make sure it's not shared.

https://google.github.io/adk-docs/sessions/state/#organizing-state-with-prefixes-scope-matters
https://google.github.io/adk-docs/runtime/api-server/#session-management