Extracting credentials from headers for tool usage

[rohan-kavari]

I am invoking an Agent Engine–deployed agent using the Reasoning Engine query API:

POST https://${location}-aiplatform.googleapis.com/v1/projects/${projectId}/locations/${location}/reasoningEngines/${agentId}:query

Client-side request:

const res = await fetch(url, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    class_method: method,
    input
  })
})

On the agent side, I want to access the same OAuth access token that was used by the caller, so that I can use it for downstream tool usage (for example, calling other Google APIs while preserving the caller’s identity and permissions).

Question

• Is the caller’s access token available inside the Agent Engine runtime?
• If yes, what is the supported way to extract it inside the reasoning engine or tool execution context?

Goal

Ensure downstream API calls made by tools execute with the caller’s authorization context, rather than a fixed service account.

Any guidance or examples would be appreciated.

---

[adk-bot]

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

TLDR: Directly accessing the caller's OAuth access token from the inbound request is not a supported feature in ADK. The recommended approach is to leverage ADK's built-in tool authentication mechanisms to manage credentials for downstream API calls in a secure and scalable way.

---

Hello! That's a great question about handling authentication and preserving user identity for tool calls.

For security and design reasons, the ADK framework does not directly expose the caller's inbound access token to the tool execution context. Instead, it provides a robust mechanism for tools to declare their own authentication requirements and manage credentials securely. This ensures that tools only have access to the specific permissions they need, rather than inheriting the broader permissions of the calling user.

The recommended way to handle this is to define the authentication needs within your tool. When the tool is called, the ADK runtime will determine if the necessary credentials are in the session state. If not, it will automatically trigger the authentication flow you've configured. [1, 4, 11]

You can use tool_context.request_credential(AUTH_CONFIG) within your tool to initiate this process. [4] The ADK framework then handles the user-facing authentication steps and securely stores the obtained credentials for subsequent tool calls within the session. [1]

This approach has several advantages:

• Security: It adheres to the principle of least privilege. Your tool gets a token specifically for the downstream API it needs to call, with only the necessary scopes.
• Scalability: It allows you to manage authentication for multiple tools and APIs in a consistent way.
• User Experience: ADK handles the complexities of the OAuth flow, prompting the user for consent only when needed.

For more detailed information and examples, you can refer to the documentation on tool authentication. [4, 11]

While this means you can't directly use the incoming token, this approach provides a more secure and flexible way to manage authorization for your tools.

[1] publicly accessible HTTPS URL of the document
[4] publicly accessible HTTPS URL of the document
[11] publicly accessible HTTPS URL of the document

[lucaslimacodes]

@rohan-kavari Were you able to get the user's access token within the agent's tool context?

[rohan-kavari]

No not from headers, But you can send the token as state in request body which is accessible via tool context.

[lucaslimacodes]

interesting.

do you have any link with the documentation describing this behavior?

[usuallyunusual]

@rohan-kavari Is the agent-engine state considered safe to hold short-lived bearer tokens?
@adk-bot Answer the above

[usuallyunusual]

@adk-bot
Is the agent-engine state considered safe to hold short-lived bearer tokens?

[adk-bot]

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

TLDR: Yes, it is possible to use the caller's authorization context for downstream tool usage. This is achieved by configuring your agent to work with Gemini Enterprise, which then passes the necessary OAuth token to your agent's tool_context.

---

Hello! Thank you for your question.

The functionality you're asking about is a supported scenario, particularly when an agent deployed to Agent Engine is used with Gemini Enterprise. Instead of manually extracting the token from the request headers, the platform handles the authorization flow and makes the token available to your tools.

Here’s how it generally works:

1. Authorization Setup in Gemini Enterprise: You need to create an Authorization resource in Gemini Enterprise, which is linked to OAuth 2.0 credentials in your Google Cloud project. This setup will have a unique identifier (let's call it AUTH_ID).

2. Agent Configuration: In your agent's code, you configure it to consume the access token that will be provided by Gemini Enterprise. This is typically done by setting the credentials type to expect an HTTP credential.

3. Token in tool_context: When the agent is invoked via Gemini Enterprise, an OAuth access token is generated on behalf of the end-user. This token is then passed into the ADK tool_context with a specific key that corresponds to your authorization setup (AUTH_ID). Your tools can then retrieve the token from the tool_context to make authenticated downstream API calls.

This ensures that the tools operate within the permissions of the original caller, rather than using a fixed service account identity.

For a practical example of this, you can refer to the BigQuery sample in the ADK repository, which demonstrates a similar end-to-end authorization flow.

[1] https://github.com/google/adk-python/blob/main/contributing/samples/bigquery/README.md

[adk-bot]

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

TLDR: Yes, the caller's access token is available in the tool_context when the agent is invoked through a platform like Gemini Enterprise. You can configure your agent to use these credentials for downstream API calls.

---

Hello! Based on the information in the ADK documentation, here’s how you can handle user credentials for downstream tool usage in your Agent Engine-deployed agent.

When an agent is deployed to Agent Engine and invoked through a platform like Gemini Enterprise, the end-user's OAuth access token is passed into the tool_context. This is designed to allow tools to make API calls with the same permissions as the original caller.

The ADK provides a mechanism to consume this token. You will need to configure your agent to use HTTP credentials. You can see a practical example of this in the BigQuery Tools Sample, which demonstrates how to set up an agent to use the caller's credentials to interact with the BigQuery API. [1]

To configure your agent to use the passed-in access token, you should set the CREDENTIALS_TYPE to AuthCredentialTypes.HTTP in your agent's configuration. The ADK framework will then look for the access token in the tool_context and automatically use it for authenticated requests made by your tools.

For this to work, you also need to create an Authorization resource in Gemini Enterprise and link it to your OAuth 2.0 credentials. When a user invokes the agent, Gemini Enterprise will handle the OAuth flow, obtain an access token, and pass it to your agent.

I hope this helps you achieve your goal of preserving the caller's authorization context in your downstream API calls.

---

[1] https://github.com/google/adk-python/blob/main/contributing/samples/bigquery/README.md