Skip to main content

AAuth Quickstart — OpenAI Agents SDK

Wire the AAuth protocol into an OpenAI Agents SDK agent so every tool call carries a cryptographically-signed identity. The agent's identity is an Ed25519 key pair registered with LumoAuth; the access token is obtained once from the AAuth token endpoint; every request is signed with RFC 9421 HTTP Message Signatures (per-request, replay-proof proof of possession).

Prerequisites
  • LumoAuth organization with AAuth enabled
  • Python 3.9+

Complete Steps 1–3 first (generate a key pair, register the agent and the resource), and ideally verify with the Python SDK quickstart before wiring the Agents SDK.

Install​

pip install lumoauth[aauth] openai-agents

Example​

import asyncio
from agents import Agent, Runner, function_tool
from lumoauth.aauth import AAuthClient

# 1. Initialize the AAuth client
private_pem, jwks = AAuthClient.generate_keypair()
aauth = AAuthClient(
    agent_identifier="https://my-agent.example.com",
    private_key_pem=private_pem,
    org_id="acme-corp",
)

# 2. Obtain tokens upfront (resource token from your resource server)
resource_token = "..."
tokens = aauth.request_authorization(resource_token=resource_token, scope="read write")
if tokens.get("authorization_required"):
    raise RuntimeError("User consent required - implement OAuth redirect flow first")

ACCESS_TOKEN = tokens["access_token"]

# 3. Define tools that make AAuth-signed API calls
@function_tool
def fetch_document(document_id: str) -> str:
    """Fetch a document from the protected API."""
    resp = aauth.signed_request(
        "GET",
        f"https://api.example.com/v1/documents/{document_id}",
        auth_token=ACCESS_TOKEN,
    )
    if resp.status_code == 200:
        return resp.text
    return f"Error: HTTP {resp.status_code}"

@function_tool
def create_summary(document_id: str, summary: str) -> str:
    """Create a summary for a document in the protected API."""
    resp = aauth.signed_request(
        "POST",
        f"https://api.example.com/v1/documents/{document_id}/summaries",
        auth_token=ACCESS_TOKEN,
        json={"text": summary},
    )
    if resp.status_code in (200, 201):
        return "Summary created successfully."
    return f"Error: HTTP {resp.status_code}"

# 4. Create the OpenAI Agent
research_agent = Agent(
    name="Research Assistant",
    instructions=(
        "You are a helpful assistant with access to a protected document API. "
        "Retrieve documents and create summaries as requested."
    ),
    tools=[fetch_document, create_summary],
)

# 5. Run the agent
async def main():
    result = await Runner.run(
        research_agent,
        "Fetch document doc-42 and create a two-sentence summary.",
    )
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

How it works​

ComponentRole
AAuthClientManages key material and handles AAuth token exchange
aauth.signed_request(...)Adds the RFC 9421 Agent-Auth signature header and the Authorization header
@function_toolDecorates Python functions as OpenAI SDK tools
ACCESS_TOKENShort-lived token issued after agent + resource validation

Next steps​