Connect an agent to a third-party data tool with user authorization

Goal

Access third-party data only with scopes explicitly granted by the user, without exposing long-lived credentials to the agent.

Steps

1. Identify resources accessed for one user and the OAuth scopes supported by the provider. [auth]
2. Declare OAuth with AuthConfig(auth_scheme=..., raw_auth_credential=..., credential_key="documents_api") and configure a credential service for CredentialManager. [auth]
3. When authorization interrupts the run, send the user to the provider consent screen; never put tokens in model messages. [auth]
4. After callback, validate state and user binding, return credentials securely to the waiting tool, and limit lifetime. [auth]

How to verify

Authorization covers only requested scopes; invalid state, expired tokens, and another user’s token are rejected, with no token in logs.

Troubleshooting

If the tool requests consent again after resume, verify the callback returns the right authorization result to the same user session.