Metadata-Version: 2.5
Name: maigp-strands
Version: 1.2.0
Summary: AIGP governance adapter for Strands Agents SDK
Requires-Python: >=3.11
Requires-Dist: maigp-agent-core>=1.2.0
Requires-Dist: strands-agents<2,>=1.61.1
Provides-Extra: agency
Requires-Dist: maigp-agent-core[agency]>=1.2.0; extra == 'agency'
Provides-Extra: agency-aws
Requires-Dist: maigp-agent-core[agency-aws]>=1.2.0; extra == 'agency-aws'
Provides-Extra: dev
Requires-Dist: aiap-client<2,>=1.1.0; extra == 'dev'
Requires-Dist: httpx>=0.25.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
Description-Content-Type: text/markdown

# maigp-strands

AIGP governance for the Strands Agents SDK.

Part of **MAIGP** — the Mediated AI Governance Protocol: a runtime consent / scope / evidence layer for AI systems. Every governed call is **CHECK**ed before it runs (policy, scope, jurisdiction, circuit-breaker) and **RECORD**ed + **TRACE**d as tamper-evident evidence after.

## What it governs

Every model call and every tool call of a Strands agent, through a Strands `HookProvider`
(`AigpHookProvider`, requires `strands-agents>=1.61.1,<2`).

## Governance model

| Strands event | AIGP action |
|---|---|
| `BeforeModelCallEvent` | **CHECK** (`client.check`); not ALLOW → `event.cancel` (the model is not invoked) |
| `AfterModelCallEvent` | **RECORD** (tokens, latency, status) for a call that ran |
| `BeforeToolCallEvent` | **TOOL_REQUEST** (`client.tool_request`, SHA-256 of the input); not ALLOW → `event.cancel_tool` (the tool body never runs; the model gets an error tool result with the reason) |
| `AfterToolCallEvent` | **RECORD** (`use_case="tool:<name>"`, `output_ref` = SHA-256 of the tool result) for a call that ran |

Fail closed: only `ALLOW` / `ALLOW_WITH_CONSTRAINTS` lets a call run. DENY, RATE_LIMITED,
UNCHECKED, a missing decision, an unreachable authority, any error in the CHECK path, or a CHECK
slower than `check_timeout` (default 10 s) cancels the call, in ENFORCE and REPORT mode alike.
The provider refuses to register on a disabled client (empty `gov_url`) or on a Strands whose
events cannot cancel. Its before-callbacks run after all other hooks, so the CHECK covers the
call that really runs.

## Install

```bash
pip install maigp-strands
```

Pulls in [`maigp-agent-core`](https://pypi.org/project/maigp-agent-core/) (shared lifecycle),
[`maigp-client`](https://pypi.org/project/maigp-client/) and `strands-agents`.

## Quick start

```python
from strands import Agent
from aigp_strands import AigpGovernance

gov = AigpGovernance(gov_url="https://gov.example.com",
                     app_id="my-strands-agent", hmac_secret="secret")

agent = Agent(model=..., tools=[...], hooks=[gov.hook_provider()])
```

`gov.hook_provider(use_case=..., check_timeout=..., tool_version=...)` is the same as
`AigpHookProvider(gov, ...)`. `use_case` defaults to the agent's `name`.

## AIAP agency gate (opt-in, 1.2.0)

Off by default: with no gate, nothing changes. Pass an `AgencyGate` from
[`maigp-agent-core`](https://pypi.org/project/maigp-agent-core/) to the governance and the hook
provider needs an AIAP agency grant (RFC-001) after every allowing CHECK / TOOL_REQUEST and before
the model or tool runs:

```python
from aigp_agent_core import AgencyGate

gate = AgencyGate(broker_url, agent_id, token_provider,          # the agent's own token, from a callable
                  scopes={"my-strands-agent": {"resources": ["bedrock:InvokeModel"]}})
gov = AigpGovernance(gov_url=..., app_id=..., hmac_secret=..., agency=gate)
agent = Agent(name="my-strands-agent", model=..., tools=[...], hooks=[gov.hook_provider()])
```

- The scope key is the hook's `use_case` (default: the agent's `name`); the CHECK's `request_id`
  is sent as the AIGP trace id.
- The grant is kept and reused until shortly before it expires, so normally only the first model
  call reaches the broker. Use `gov.agency_session(region)` to act with the grant's credentials.
- Fail closed in every mode: a refusal, an unreachable broker, an empty token, a failing token
  provider, a missing `aiap-client`, or a gate slower than `check_timeout` cancels the call
  (`event.cancel` / `event.cancel_tool`, text `Blocked by AIAP agency: ...`). A call cancelled by its
  CHECK never asks the broker.
- Install: `pip install 'maigp-strands[agency]'` (`[agency-aws]` adds boto3).

## Deprecated: `AigpCallbackHandler`

`AigpCallbackHandler` / `gov.callback_handler()` **does not govern**: Strands callback handlers
receive streamed output only and cannot block a call, and Strands never calls its `on_*`
methods. Before 1.1.0 it was not even callable, so `Agent(callback_handler=...)` failed on the
first event. Since 1.1.0 it **fails closed**: it warns (`DeprecationWarning`) when built, and wired
as `Agent(callback_handler=...)` it raises `AigpCallbackHandlerNotGoverning` on Strands' first
event, before the model is called or any tool runs, so an agent wired the old way refuses to run
rather than running ungoverned. It will be removed in 2.0. Replace `callback_handler=gov.callback_handler()` with
`hooks=[gov.hook_provider()]`.

## Links

- Protocol, specs & full adapter catalog: https://github.com/owner-spec/aigp-protocol
- Issues: https://github.com/owner-spec/aigp-protocol/issues

---

License: Proprietary. © Kanjani AI Research & Causum.
