> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Agents SDK

> Scope-enforced FunctionTool wrappers for the OpenAI Agents SDK.

## Install

```bash theme={null}
pip install grantex-openai-agents
```

OpenAI Agents SDK is a peer dependency:

```bash theme={null}
pip install openai-agents
```

## Quick Start

```python theme={null}
from grantex_openai_agents import create_grantex_tool

tool = create_grantex_tool(
    name="read_calendar",
    description="Read upcoming calendar events",
    grant_token=grant_token,       # JWT from Grantex authorization flow
    required_scope="calendar:read",
    func=get_calendar_events,
)

# Use with any OpenAI Agents SDK agent
from agents import Agent
agent = Agent(name="assistant", tools=[tool])
```

If the grant token doesn't include the required scope, `create_grantex_tool` raises a `PermissionError` immediately — the tool is never created.

## API Reference

### `create_grantex_tool()`

Creates an OpenAI Agents SDK `FunctionTool` that verifies the token against the configured JWKS endpoint before enforcing scopes from verified claims.

| Parameter | Type | Description |
| - | - | - |
| `name` | `str` | Tool name |
| `description` | `str` | Tool description |
| `grant_token` | `str` | JWT grant token from Grantex |
| `required_scope` | `str` | Scope that must be present in the token |
| `func` | `Callable[..., str]` | The function to wrap |

### `get_tool_scopes(grant_token)`

Returns unverified scopes decoded from a grant token. Use this only for display or debugging, never for authorization.

### `decode_jwt_payload(token)`

Decodes the payload of a JWT without verifying the signature. Useful for inspecting token claims.

## Requirements

* Python 3.9+
* `grantex` >= 0.1.0
* `openai-agents` >= 0.0.3 (peer dependency)

## Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: [sanjeev@orchestrum.in](mailto:sanjeev@orchestrum.in) or [mishra.sanjeev@gmail.com](mailto:mishra.sanjeev@gmail.com).

## Current Authority and Human Identity

Use the exact integration version and minimum primary SDK in [Release Status](/release-status).
Per-invocation issuer authority and trusted principal/agent binding are opt-in.
Configure the callback with the trusted issuer and derive identity from the host's
authenticated session; signature and scope checks alone do not prove current
revocation or human consent. See [SDK execution authority](/guides/sdk-execution-authority)
for configuration, denial behavior and manifest/decision/caps boundaries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.