How to pass a bearer token to tools when a bearer token is specified in Authorization HTTP Header in a request from client to a adk application?

[kyu08]

Thank you for maintaining ADK always!

Situation

We are building an application like below. ADK application receives request from frontend and it calls backend API within tool.

We pass a bearer token which specified as Authorization HTTP Header when we request from frontend to ADK application.
And then we want to specify Authorization HTTP Header when we request to the backend API within ADK tool functions.

Question

I didn't understand how to pass a bearer token which came from frontend to a tool which calls backend API using adk-python though I read and search GitHub issue and PRs.
Or could we pass a bearer token as a part of request body to ADK? Or could we make a HTTP request to ADK to save a token to memory before invoking agent?
Could you please tell me how?

Thank you.

[adk-bot]

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

TLDR: Use ADK's Session State to pass the bearer token from your web server endpoint to your tool. Your server code will add the token to the state, and your tool will read it from the ToolContext.

---

Hello! Thank you for the great question. This is a common and important pattern for building secure applications with ADK. Here’s a detailed guide on how you can achieve this.

The recommended approach is to use the Session State to pass contextual data, like an authentication token, from your application's entrypoint (e.g., your FastAPI endpoint) down to your tool functions.

Step 1: Capture the Token in Your Application Endpoint

First, in your web server code, you need to capture the bearer token from the Authorization header. You then add this token to the session state before running the agent.

Here is a conceptual example using FastAPI:

from fastapi import FastAPI, Header, Depends
from typing import Annotated
from google.adk.runners import Runner
from google.adk.sessions import Session

# Assume 'runner' and 'session_service' are already configured
# runner: Runner = ...
# session_service: SessionService = ...

app = FastAPI()

@app.post("/invoke-agent")
async def invoke_agent(
    # Get the current session (you might have your own dependency for this)
    session: Annotated[Session, Depends(get_or_create_session)],
    # Extract the Authorization header
    authorization: Annotated[str | None, Header()] = None
):
    # 1. Add the token to the session state
    if authorization:
        session.state["bearer_token"] = authorization

    # The session with the updated state will be used by the runner
    # 2. Now, run the agent as usual
    # The runner will automatically use the updated session object
    async for event in runner.run_async(
        session=session,
        # ... other params
    ):
        # process events
        pass

    return {"status": "ok"}

Step 2: Access the Token in Your Tool

Next, modify your tool's function signature to accept tool_context: ToolContext. ADK will automatically inject this object at runtime, giving you access to the session state.

import requests
from google.adk.tools import ToolContext, tool

@tool
def call_backend_api(query: str, tool_context: ToolContext) -> dict:
    '''Calls the secure backend API.'''

    # 1. Retrieve the token from the state
    auth_header = tool_context.state.get("bearer_token")

    if not auth_header:
        return {"error": "Authentication token not found in state."}

    headers = {
        "Authorization": auth_header,
        "Content-Type": "application/json"
    }
    
    try:
        # 2. Use the token to make the authenticated request
        response = requests.post(
            "https://your-backend-api.com/endpoint",
            headers=headers,
            json={"query": query}
        )
        response.raise_for_status()  # Raise an exception for bad status codes
        return response.json()

    except requests.exceptions.RequestException as e:
        return {"error": f"API call failed: {e}"}

Why This Approach Works Best

• Decoupling: Your tool's logic remains independent of the web framework. It only needs to know about the ToolContext, not about HTTP headers or FastAPI. [1, 4]
• State Management: This leverages ADK's built-in session management, which is the intended way to handle conversational memory and context. [1, 8]
• Security: You are explicitly passing the credential for the current session, which is a secure and clear pattern.

For more details, you can refer to the official documentation on Context and Tools.

I hope this helps you build your application!

[1] https://google.github.io/adk-docs/context/
[4] https://google.github.io/adk-docs/tools/
[8] https://google.github.io/adk-docs/get-started/about/