> ## 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.

# CrewAI

> Scope-enforced, audited agent tools for CrewAI.

## Install

```bash theme={null}
pip install grantex-crewai
```

CrewAI is a peer dependency:

```bash theme={null}
pip install crewai
```

## Scope-Enforced Tools

```python theme={null}
from grantex_crewai import create_grantex_tool
from pydantic import BaseModel

class FetchParams(BaseModel):
    url: str

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 in a CrewAI agent
```

Before each protected invocation, the tool verifies the token signature and claims with `verify_grant_token()`, using the configured JWKS endpoint, and checks the verified scopes. The verifier may contact that endpoint to resolve keys, so it must be reachable. Invalid tokens and missing scopes raise before the wrapped function runs.

## Audit Logging

Wrap any Grantex tool with audit logging:

```python theme={null}
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,
)

tool = with_audit_logging(
    tool, client,
    agent_id="ag_01HXYZ...",
    grant_id="grnt_01HXYZ...",
)
# Every call is now recorded in the audit trail
```

## API Reference

### `create_grantex_tool()`

```python theme={null}
create_grantex_tool(
    *,
    name: str,
    description: str,
    grant_token: str,
    required_scope: str,
    func: Callable[..., str],
    args_schema: type[BaseModel] | None = None,
) -> BaseTool
```

| Parameter        | Description                                           |
| ---------------- | ----------------------------------------------------- |
| `name`           | Tool name (used in audit log entries)                 |
| `description`    | Human-readable description shown to the LLM           |
| `grant_token`    | Grantex grant token (RS256 JWT)                       |
| `required_scope` | Scope that must be present in the token's `scp` claim |
| `func`           | The function to execute when the tool is called       |
| `args_schema`    | Optional Pydantic `BaseModel` describing tool inputs  |

**Raises:** `PermissionError` if the grant token doesn't contain `required_scope`.

### `with_audit_logging()`

```python theme={null}
with_audit_logging(
    tool: BaseTool,
    client: Grantex,
    *,
    agent_id: str,
    grant_id: str,
) -> BaseTool
```

### `get_tool_scopes(grant_token)`

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

## Requirements

* Python 3.9+
* `grantex` >= 0.1.0
* `crewai` >= 0.28.0 (peer dependency)