grantex-strands 0.1.0

Grantex scope enforcement for Strands Agents SDK

grantex-strands

Strands Agents SDK integration for the Grantex delegated authorization protocol - scope-enforced agent tools.

Wrap Strands tool functions with Grantex grant token scope checks so agents only receive tools they have been authorized to use.

Homepage | Docs | GitHub

Install

pip install grantex-strands

You also need the Strands Agents SDK installed:

pip install strands-agents

Quick Start

from grantex_strands import create_grantex_tool

def get_calendar_events(date: str = "") -> str:
    return f"events for {date}"

read_calendar = create_grantex_tool(
    name="read_calendar",
    description="Read upcoming calendar events",
    grant_token=grant_token,
    required_scope="calendar:read",
    func=get_calendar_events,
)

# Pass read_calendar into your Strands agent tools list.

If the grant token does not include the required scope, create_grantex_tool raises PermissionError immediately and the tool is not created.

Enforcement Modes

Offline mode is the default. It decodes the grant token payload and checks the scp claim without a network call:

tool = create_grantex_tool(
    name="read_calendar",
    description="Read upcoming calendar events",
    grant_token=grant_token,
    required_scope="calendar:read",
    func=get_calendar_events,
)

Online mode delegates enforcement to a Grantex client:

tool = create_grantex_tool(
    name="read_calendar",
    description="Read upcoming calendar events",
    grant_token=grant_token,
    required_scope="calendar:read",
    func=get_calendar_events,
    client=grantex_client,
    connector="calendar",
    online=True,
)

API Reference

create_grantex_tool()

Creates a Strands-compatible tool with Grantex scope enforcement.

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]	Function to wrap
client	Any	Grantex client instance for online mode
connector	str | None	Connector name for online mode
online	bool	Use client.enforce() instead of offline JWT scope checking

get_tool_scopes()

Returns the scopes embedded in a grant token. Invalid tokens return an empty list.

Requirements

• Python 3.11+
• strands-agents >= 0.1

Grantex Ecosystem

This package is part of the Grantex ecosystem. See also:

• grantex - Core Python SDK
• grantex-crewai - CrewAI integration
• grantex-openai-agents - OpenAI Agents SDK integration
• grantex-adk - Google ADK integration

License

MIT