chore: auth0 sample (Auth for Headless Agents)

[siacomuzzi]

Auth for Headless Agents sample

This sample demonstrates how headless agent's tools can leverage Auth0's Client-Initiated Backchannel Authentication (CIBA) flow to request user authorization via push notification and obtain tokens for accessing separate APIs.

Additionally, it shows agent-level authorization via the OAuth 2.0 Client Credentials flow.

How It Works

Allows an A2A client to interact with an external HR Agent, owned by Staff0, to verify whether the provided user data corresponds to an active Staff0 employee.
With the user’s authorization (via push notification), the Staff0 HR Agent can access the internal company HR API to retrieve their employment details.

sequenceDiagram
   participant User as John Doe
   participant A2AClient as A2A Client
   participant Auth0 as Auth0 (staff0.auth0.com)
   participant HR_Agent as Staff0 HR Agent
   participant HR_API as Staff0 HR API
   
   A2AClient->>HR_Agent: Get A2A Agent Card
   HR_Agent-->>A2AClient: Agent Card
   A2AClient->>Auth0: Request access token (client credentials)
   Auth0-->>A2AClient: Access Token
   A2AClient->>HR_Agent: Is John Doe, with email [email protected], an active employee at Staff0? (Access Token)
   HR_Agent->>Auth0: Request access token (CIBA)
   Auth0->>User: Push notification to approve access
   User-->>Auth0: Approves access
   Auth0-->>HR_Agent: Access Token
   HR_Agent->>HR_API: Retrieve employment details (Access Token)
   HR_API-->>HR_Agent: Employment details
   HR_Agent-->>A2AClient: Yes, John Doe is an active employee.

Loading

uv run --prerelease=allow test_client.py

======= Agent Card ========
{"name":"Staff0 HR Agent","description":"This agent handles external verification requests about Staff0 employees made by third parties.","url":"http://0.0.0.0:10050/","version":"1.0.0","capabilities":{"streaming":true,"pushNotifications":false,"stateTransitionHistory":false},"defaultInputModes":["text","text/plain"],"defaultOutputModes":["text","text/plain"],"skills":[{"id":"is_active_employee","name":"Check Employment Status Tool","description":"Confirm whether a person is an active employee of the company.","tags":["employment"],"examples":["Is John Doe (with email [email protected]) an active employee?"]}]}

=========  Starting a New Task ========
What do you want to send to the agent? (:q or quit to exit): Does John Doe with email [email protected] work at Staff0?

stream message => role: user, type: text, text: Does John Doe with email [email protected] work at Staff0?
stream message => role: agent, type: text, text: Looking up the employment status...
stream message => role: agent, type: text, text: Processing the employment status...
stream message => role: agent, type: text, text: Looking up the employment status...
stream message => role: agent, type: text, text: Processing the employment status...
stream artifact => type: text, text: Yes, John Doe is an active employee at Staff0.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[holtskinner]

Please move this PR to the samples/ directory and have it use the SDK from https://github.com/google/a2a-python/

[siacomuzzi]

Move this sample to the samples/ directory

got it, and consuming SDK from https://github.com/google/a2a-python instead of samples/python/common/ directory.

[siacomuzzi]

BTW, https://github.com/google/a2a-python is currently using AgentCard -> authentication attribute.
Do you have any plans to update it to use securitySchemes and security soon?
Thank you

https://github.com/google/a2a-python/blob/5dd2ed1cc8041f916d2cf84890af2ffb5150232e/src/a2a/types.py#L657-L666C5

[siacomuzzi]

PR is ready for review cc @holtskinner

[swapydapy]

Yes. There are new updates to spec which will be rolled out soon. They will have securitySchemes and security, following OpenAPI's security spec.