# Auth-Agent Agent SDK (Python)
**Server-side SDK for AI agents to authenticate with Auth-Agent OAuth 2.1**
This SDK is for **AI agent developers** who want their agents to authenticate and access OAuth-protected resources.
> **Note:** If you're a website developer wanting to add "Sign in with Auth-Agent", use [`@auth-agent/client-sdk`](../client-sdk-ts/) instead.
## Installation
```bash
pip install auth-agent
```
## Quick Start
```python
from auth_agent import AgentSDK
# Initialize SDK (get credentials from https://console.auth-agent.com)
sdk = AgentSDK(
agent_id="your-agent-id",
agent_secret="your-agent-secret",
model_name="openai/gpt-4o"
)
# Step 1: Authenticate agent
auth_response = sdk.authenticate_agent(
client_id="oauth-client-id",
redirect_uri="https://your-app.com/callback"
)
# Step 2: Get AI challenge
challenge = sdk.get_challenge(auth_response.session_id)
print(f"Challenge: {challenge.challenge}")
# Step 3: Generate answer using your AI model
answer = your_ai_model.generate(challenge.challenge)
# Step 4: Verify challenge
result = sdk.verify_challenge(auth_response.session_id, answer)
auth_code = result["authorization_code"]
# Step 5: Exchange code for tokens
tokens = sdk.exchange_code_for_token(
code=auth_code,
redirect_uri="https://your-app.com/callback",
client_id="oauth-client-id"
)
# Step 6: Access protected resources
user_info = sdk.get_user_info()
print(f"Agent ID: {user_info.agent_id}")
print(f"Model: {user_info.model_name}")
```
## Configuration
The SDK requires only 3 parameters:
- **agent_id**: Your agent identifier (register at [console.auth-agent.com](https://console.auth-agent.com))
- **agent_secret**: Your agent secret for authentication
- **model_name**: Your AI model (e.g., `"openai/gpt-4o"`, `"anthropic/claude-3-5-sonnet"`)
The server URL is hardcoded to `https://api.auth-agent.com` and cannot be changed.
## Features
- ✅ **OAuth 2.1 compliant** - Full OAuth 2.1 with PKCE support
- ✅ **OIDC support** - OpenID Connect UserInfo and Discovery
- ✅ **AI challenge authentication** - Unique agent verification
- ✅ **Token management** - Automatic token refresh and expiration tracking
- ✅ **Type hints** - Full typing support with Pydantic models
- ✅ **Context manager** - Automatic resource cleanup
## Usage Examples
### Basic Authentication Flow
```python
from auth_agent import AgentSDK
# Using context manager (recommended)
with AgentSDK(
agent_id="your-agent-id",
agent_secret="your-agent-secret",
model_name="openai/gpt-4o"
) as sdk:
# Authenticate
auth = sdk.authenticate_agent(
client_id="client-id",
redirect_uri="https://app.com/callback"
)
# Get challenge
challenge = sdk.get_challenge(auth.session_id)
# Your AI generates answer
answer = generate_answer(challenge.challenge)
# Verify and get tokens
result = sdk.verify_challenge(auth.session_id, answer)
tokens = sdk.exchange_code_for_token(
code=result["authorization_code"],
redirect_uri="https://app.com/callback",
client_id="client-id"
)
# Access user info
user_info = sdk.get_user_info()
print(user_info)
```
### Token Refresh
```python
from auth_agent import AgentSDK
sdk = AgentSDK(
agent_id="your-agent-id",
agent_secret="your-agent-secret",
model_name="openai/gpt-4o"
)
# Check if token is expired
if sdk.token_manager.is_expired():
# Refresh token
new_tokens = sdk.refresh_access_token()
print(f"New access token: {new_tokens.access_token}")
```
### Token Introspection
```python
# Check if token is valid
introspection = sdk.introspect_token()
if introspection.active:
print("Token is valid")
print(f"Expires at: {introspection.exp}")
else:
print("Token is invalid or expired")
```
### Get Agent Profile
```python
# Get agent profile information
profile = sdk.get_agent_profile()
print(f"Agent: {profile.agent_id}")
print(f"Model: {profile.model_name}")
print(f"Created: {profile.created_at}")
```
### Discovery Document
```python
# Get OIDC discovery document
discovery = sdk.get_discovery_document()
print(f"Issuer: {discovery['issuer']}")
print(f"Authorization endpoint: {discovery['authorization_endpoint']}")
```
## Error Handling
```python
from auth_agent import (
AgentSDK,
AuthenticationError,
TokenError,
ValidationError,
NetworkError
)
try:
sdk = AgentSDK(
agent_id="your-agent-id",
agent_secret="your-agent-secret",
model_name="openai/gpt-4o"
)
auth = sdk.authenticate_agent(
client_id="client-id",
redirect_uri="https://app.com/callback"
)
except ValidationError as e:
print(f"Invalid parameters: {e.message}")
except AuthenticationError as e:
print(f"Authentication failed: {e.message} ({e.error_code})")
except TokenError as e:
print(f"Token error: {e.message}")
except NetworkError as e:
print(f"Network error: {e.message}")
```
## API Reference
### AgentSDK
Main SDK class for authentication.
#### Constructor
```python
AgentSDK(
agent_id: str,
agent_secret: str,
model_name: str,
timeout: float = 30.0
)
```
#### Methods
- **authenticate_agent()** - Start authentication flow
- **get_challenge()** - Fetch AI challenge
- **verify_challenge()** - Submit challenge answer
- **exchange_code_for_token()** - Exchange auth code for tokens
- **refresh_access_token()** - Refresh access token
- **revoke_token()** - Revoke token
- **get_user_info()** - Get OIDC UserInfo
- **introspect_token()** - Check token validity
- **get_agent_profile()** - Get agent profile
- **get_discovery_document()** - Get OIDC discovery
### Models
All models are Pydantic models with full type validation:
- **AgentAuthRequest** - Authentication request
- **AgentAuthResponse** - Authentication response with session_id
- **ChallengeResponse** - AI challenge data
- **TokenResponse** - OAuth token response
- **UserInfo** - OIDC UserInfo
- **AgentProfile** - Agent profile data
- **IntrospectionResponse** - Token introspection result
### Exceptions
- **AuthAgentError** - Base exception
- **AuthenticationError** - Authentication failures
- **TokenError** - Token operation failures
- **ValidationError** - Input validation errors
- **NetworkError** - Network request failures
## Requirements
- Python 3.8+
- httpx >= 0.24.0
- pydantic >= 2.0.0
## Development
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black .
# Type checking
mypy auth_agent
```
## License
MIT License
## Support
- Documentation: [docs.auth-agent.com](https://docs.auth-agent.com)
- Console: [console.auth-agent.com](https://console.auth-agent.com)
- Issues: [github.com/auth-agent/python-sdk/issues](https://github.com/auth-agent/python-sdk/issues)
Raw data
{
"_id": null,
"home_page": "https://github.com/auth-agent/agent-sdk-python",
"name": "auth-agent-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "oauth, oauth2, oauth2.1, oidc, authentication, ai, agents, agent-sdk, gpt, claude, chatbot, python",
"author": "Auth-Agent Team",
"author_email": "Auth-Agent Team <support@auth-agent.com>",
"download_url": "https://files.pythonhosted.org/packages/95/9f/66938c8030aacbcf9dea482743f6b4ecd362e89fbe9d72c1f3f271a04863/auth_agent_sdk-2.1.0.tar.gz",
"platform": null,
"description": "# Auth-Agent Agent SDK (Python)\n\n**Server-side SDK for AI agents to authenticate with Auth-Agent OAuth 2.1**\n\nThis SDK is for **AI agent developers** who want their agents to authenticate and access OAuth-protected resources.\n\n> **Note:** If you're a website developer wanting to add \"Sign in with Auth-Agent\", use [`@auth-agent/client-sdk`](../client-sdk-ts/) instead.\n\n## Installation\n\n```bash\npip install auth-agent\n```\n\n## Quick Start\n\n```python\nfrom auth_agent import AgentSDK\n\n# Initialize SDK (get credentials from https://console.auth-agent.com)\nsdk = AgentSDK(\n agent_id=\"your-agent-id\",\n agent_secret=\"your-agent-secret\",\n model_name=\"openai/gpt-4o\"\n)\n\n# Step 1: Authenticate agent\nauth_response = sdk.authenticate_agent(\n client_id=\"oauth-client-id\",\n redirect_uri=\"https://your-app.com/callback\"\n)\n\n# Step 2: Get AI challenge\nchallenge = sdk.get_challenge(auth_response.session_id)\nprint(f\"Challenge: {challenge.challenge}\")\n\n# Step 3: Generate answer using your AI model\nanswer = your_ai_model.generate(challenge.challenge)\n\n# Step 4: Verify challenge\nresult = sdk.verify_challenge(auth_response.session_id, answer)\nauth_code = result[\"authorization_code\"]\n\n# Step 5: Exchange code for tokens\ntokens = sdk.exchange_code_for_token(\n code=auth_code,\n redirect_uri=\"https://your-app.com/callback\",\n client_id=\"oauth-client-id\"\n)\n\n# Step 6: Access protected resources\nuser_info = sdk.get_user_info()\nprint(f\"Agent ID: {user_info.agent_id}\")\nprint(f\"Model: {user_info.model_name}\")\n```\n\n## Configuration\n\nThe SDK requires only 3 parameters:\n\n- **agent_id**: Your agent identifier (register at [console.auth-agent.com](https://console.auth-agent.com))\n- **agent_secret**: Your agent secret for authentication\n- **model_name**: Your AI model (e.g., `\"openai/gpt-4o\"`, `\"anthropic/claude-3-5-sonnet\"`)\n\nThe server URL is hardcoded to `https://api.auth-agent.com` and cannot be changed.\n\n## Features\n\n- \u2705 **OAuth 2.1 compliant** - Full OAuth 2.1 with PKCE support\n- \u2705 **OIDC support** - OpenID Connect UserInfo and Discovery\n- \u2705 **AI challenge authentication** - Unique agent verification\n- \u2705 **Token management** - Automatic token refresh and expiration tracking\n- \u2705 **Type hints** - Full typing support with Pydantic models\n- \u2705 **Context manager** - Automatic resource cleanup\n\n## Usage Examples\n\n### Basic Authentication Flow\n\n```python\nfrom auth_agent import AgentSDK\n\n# Using context manager (recommended)\nwith AgentSDK(\n agent_id=\"your-agent-id\",\n agent_secret=\"your-agent-secret\",\n model_name=\"openai/gpt-4o\"\n) as sdk:\n # Authenticate\n auth = sdk.authenticate_agent(\n client_id=\"client-id\",\n redirect_uri=\"https://app.com/callback\"\n )\n\n # Get challenge\n challenge = sdk.get_challenge(auth.session_id)\n\n # Your AI generates answer\n answer = generate_answer(challenge.challenge)\n\n # Verify and get tokens\n result = sdk.verify_challenge(auth.session_id, answer)\n tokens = sdk.exchange_code_for_token(\n code=result[\"authorization_code\"],\n redirect_uri=\"https://app.com/callback\",\n client_id=\"client-id\"\n )\n\n # Access user info\n user_info = sdk.get_user_info()\n print(user_info)\n```\n\n### Token Refresh\n\n```python\nfrom auth_agent import AgentSDK\n\nsdk = AgentSDK(\n agent_id=\"your-agent-id\",\n agent_secret=\"your-agent-secret\",\n model_name=\"openai/gpt-4o\"\n)\n\n# Check if token is expired\nif sdk.token_manager.is_expired():\n # Refresh token\n new_tokens = sdk.refresh_access_token()\n print(f\"New access token: {new_tokens.access_token}\")\n```\n\n### Token Introspection\n\n```python\n# Check if token is valid\nintrospection = sdk.introspect_token()\nif introspection.active:\n print(\"Token is valid\")\n print(f\"Expires at: {introspection.exp}\")\nelse:\n print(\"Token is invalid or expired\")\n```\n\n### Get Agent Profile\n\n```python\n# Get agent profile information\nprofile = sdk.get_agent_profile()\nprint(f\"Agent: {profile.agent_id}\")\nprint(f\"Model: {profile.model_name}\")\nprint(f\"Created: {profile.created_at}\")\n```\n\n### Discovery Document\n\n```python\n# Get OIDC discovery document\ndiscovery = sdk.get_discovery_document()\nprint(f\"Issuer: {discovery['issuer']}\")\nprint(f\"Authorization endpoint: {discovery['authorization_endpoint']}\")\n```\n\n## Error Handling\n\n```python\nfrom auth_agent import (\n AgentSDK,\n AuthenticationError,\n TokenError,\n ValidationError,\n NetworkError\n)\n\ntry:\n sdk = AgentSDK(\n agent_id=\"your-agent-id\",\n agent_secret=\"your-agent-secret\",\n model_name=\"openai/gpt-4o\"\n )\n\n auth = sdk.authenticate_agent(\n client_id=\"client-id\",\n redirect_uri=\"https://app.com/callback\"\n )\n\nexcept ValidationError as e:\n print(f\"Invalid parameters: {e.message}\")\nexcept AuthenticationError as e:\n print(f\"Authentication failed: {e.message} ({e.error_code})\")\nexcept TokenError as e:\n print(f\"Token error: {e.message}\")\nexcept NetworkError as e:\n print(f\"Network error: {e.message}\")\n```\n\n## API Reference\n\n### AgentSDK\n\nMain SDK class for authentication.\n\n#### Constructor\n\n```python\nAgentSDK(\n agent_id: str,\n agent_secret: str,\n model_name: str,\n timeout: float = 30.0\n)\n```\n\n#### Methods\n\n- **authenticate_agent()** - Start authentication flow\n- **get_challenge()** - Fetch AI challenge\n- **verify_challenge()** - Submit challenge answer\n- **exchange_code_for_token()** - Exchange auth code for tokens\n- **refresh_access_token()** - Refresh access token\n- **revoke_token()** - Revoke token\n- **get_user_info()** - Get OIDC UserInfo\n- **introspect_token()** - Check token validity\n- **get_agent_profile()** - Get agent profile\n- **get_discovery_document()** - Get OIDC discovery\n\n### Models\n\nAll models are Pydantic models with full type validation:\n\n- **AgentAuthRequest** - Authentication request\n- **AgentAuthResponse** - Authentication response with session_id\n- **ChallengeResponse** - AI challenge data\n- **TokenResponse** - OAuth token response\n- **UserInfo** - OIDC UserInfo\n- **AgentProfile** - Agent profile data\n- **IntrospectionResponse** - Token introspection result\n\n### Exceptions\n\n- **AuthAgentError** - Base exception\n- **AuthenticationError** - Authentication failures\n- **TokenError** - Token operation failures\n- **ValidationError** - Input validation errors\n- **NetworkError** - Network request failures\n\n## Requirements\n\n- Python 3.8+\n- httpx >= 0.24.0\n- pydantic >= 2.0.0\n\n## Development\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Format code\nblack .\n\n# Type checking\nmypy auth_agent\n```\n\n## License\n\nMIT License\n\n## Support\n\n- Documentation: [docs.auth-agent.com](https://docs.auth-agent.com)\n- Console: [console.auth-agent.com](https://console.auth-agent.com)\n- Issues: [github.com/auth-agent/python-sdk/issues](https://github.com/auth-agent/python-sdk/issues)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Agent SDK for AI agent developers - Authenticate AI agents with Auth-Agent OAuth 2.1, solve AI challenges, and access OAuth-protected resources",
"version": "2.1.0",
"project_urls": {
"Documentation": "https://docs.auth-agent.com",
"Homepage": "https://auth-agent.com",
"Issues": "https://github.com/auth-agent/agent-sdk-python/issues",
"Repository": "https://github.com/auth-agent/agent-sdk-python"
},
"split_keywords": [
"oauth",
" oauth2",
" oauth2.1",
" oidc",
" authentication",
" ai",
" agents",
" agent-sdk",
" gpt",
" claude",
" chatbot",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ecca5626e5e8a14e341238e2c5bb33a8bc830874224ea4b8fb481ca918b9ac70",
"md5": "f479fa9c7d8e284461574be187c2468b",
"sha256": "e09decf1d5815a886f23becee321f7db780e9246f29fc9156032bd9a41d6c4d8"
},
"downloads": -1,
"filename": "auth_agent_sdk-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f479fa9c7d8e284461574be187c2468b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12881,
"upload_time": "2025-10-26T09:45:58",
"upload_time_iso_8601": "2025-10-26T09:45:58.292707Z",
"url": "https://files.pythonhosted.org/packages/ec/ca/5626e5e8a14e341238e2c5bb33a8bc830874224ea4b8fb481ca918b9ac70/auth_agent_sdk-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "959f66938c8030aacbcf9dea482743f6b4ecd362e89fbe9d72c1f3f271a04863",
"md5": "7bd9e1532c6133a524853b19cd4ee262",
"sha256": "b8a7ead781328a09ca2c7b18b6e7f7948c549c23cb4349ad7fe38a7fc51f4a33"
},
"downloads": -1,
"filename": "auth_agent_sdk-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "7bd9e1532c6133a524853b19cd4ee262",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15745,
"upload_time": "2025-10-26T09:45:59",
"upload_time_iso_8601": "2025-10-26T09:45:59.332934Z",
"url": "https://files.pythonhosted.org/packages/95/9f/66938c8030aacbcf9dea482743f6b4ecd362e89fbe9d72c1f3f271a04863/auth_agent_sdk-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 09:45:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "auth-agent",
"github_project": "agent-sdk-python",
"github_not_found": true,
"lcname": "auth-agent-sdk"
}
JSON
