grantex-crewai

CrewAI integration for the Grantex delegated authorization protocol — scope-enforced, audited agent tools.

Wrap any CrewAI tool with Grantex grant token verification so your agents can only use tools they've been authorized for, with a full audit trail.

Homepage | Docs | Sign Up Free | GitHub

Install

pip install grantex-crewai==0.1.8

You also need CrewAI installed (it's a peer dependency):

pip install crewai

Quick start

from grantex_crewai import create_grantex_tool
from pydantic import BaseModel

# Define the tool's input schema
class FetchParams(BaseModel):
    url: str

# Create a scope-enforced tool
tool = create_grantex_tool(
    name="fetch_data",
    description="Fetches data from the given URL.",
    grant_token="eyJhbGciOiJSUzI1NiIs...",  # Grantex JWT
    required_scope="data:read",
    func=lambda url: requests.get(url).text,
    args_schema=FetchParams,
)

# Use it in a CrewAI agent — if the token doesn't have
# the "data:read" scope, create_grantex_tool raises immediately

The tool verifies the grant token against JWKS at creation time and before each run, then checks the verified scp claim. If the required scope is missing, a PermissionError is raised before the wrapped function runs.

Audit logging

Wrap any Grantex tool with audit logging to record every invocation to the Grantex audit trail:

from grantex import Grantex
from grantex_crewai import create_grantex_tool, with_audit_logging

client = Grantex(api_key="YOUR_API_KEY")

tool = create_grantex_tool(
    name="send_email",
    description="Sends an email.",
    grant_token=token,
    required_scope="email:send",
    func=send_email_fn,
)

# Wrap with audit logging — every call is recorded
tool = with_audit_logging(
    tool, client,
    agent_id="ag_01HXYZ...",
    grant_id="grnt_01HXYZ...",
)

# Now use the tool in your crew
# Successful calls log status="success", failures log status="failure"

API reference

create_grantex_tool

create_grantex_tool(
    *,
    name: str,
    description: str,
    grant_token: str,
    required_scope: str,
    func: Callable[..., str],
    args_schema: type[BaseModel] | None = None,
    jwks_uri: str = "https://api.grantex.dev/.well-known/jwks.json",
    issuer: str | None = None,
    issuer_did: str | None = None,
    audience: str | None = None,
    clock_tolerance: int = 0,
) -> BaseTool

Creates a CrewAI BaseTool with Grantex scope enforcement.

Raises:

• PermissionError — if the grant token doesn't contain required_scope
• ValueError — if the grant token can't be verified
• ImportError — if crewai is not installed

with_audit_logging

with_audit_logging(
    tool: BaseTool,
    client: Grantex,
    *,
    agent_id: str,
    grant_id: str,
) -> BaseTool

Fetches the grant and agent once to validate their relationship and resolve the immutable agent DID and principal ID, then patches the tool's _run method to log complete audit entries via the Grantex client.

get_tool_scopes

get_tool_scopes(grant_token: str) -> list[str]

Returns the scopes embedded in a grant token. Purely offline — no network call, no signature check.

Requirements

• Python 3.9+
• grantex >= 0.3.12
• crewai >= 0.28.0 (peer dependency)

Links

• Grantex documentation
• Grantex Python SDK
• Protocol specification
• CrewAI documentation

Grantex Ecosystem

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

• grantex — Core Python SDK
• @grantex/sdk — TypeScript SDK
• grantex-openai-agents — OpenAI Agents SDK integration
• grantex-adk — Google ADK integration
• @grantex/mcp — MCP server for Claude Desktop / Cursor / Windsurf

License

Apache 2.0

Ownership

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

Authority hardening requires Python SDK 0.7.1 (current_authority), not just a valid JWT signature. Bind the audience and trusted human/agent identities, and check the issuer before every execution. This does not create human consent or automatically consume action decisions/spend caps. Existing offline defaults remain offline. Verify registry availability before installation. See the SDK execution authority guide.