# aria-agentkit

**Version-pinned ARIA backend integration for the [Microsoft Agent Governance Toolkit](https://github.com/microsoft/agent-governance-toolkit).**

`aria-agentkit` is a first-class, contract-tested backend integration for the official AGT governance surfaces. It connects your AGT-governed agents to [EmpowerID ARIA](https://www.empowerid.com) — the enterprise governance platform for AI agents — through rigorous adapters for policy evaluation, governance-grade audit export, and MCP remote configuration.

## What This Package Does

| Integration | AGT Extension Point | ARIA Service |
|---|---|---|
| `ARIAToolInterceptor` | `ToolCallInterceptor` | AuthZEN PDP |
| `ARIAPolicyProvider` | `PolicyProviderInterface` | AuthZEN PDP |
| `ARIAAuditBackend` | `AuditBackend` | Receipt Vault |
| `claude_desktop_config` | — | MCP Gateway |
| `mcp_session_params` | — | MCP Gateway |
| `mcp_session_params_factory` | — | MCP Gateway |

## What This Package Does NOT Do

- Reimplements AGT governance primitives
- Proxies LLM traffic (see `aria-shield-sdk` for that)
- Provides budget management (deferred until transactional semantics are designed)
- Provides approval workflows (deferred until persisted workflow model is built)

## Version Compatibility

| `aria-agentkit` | `agent-os-kernel` | Python |
|---|---|---|
| 0.1.x | 3.0.0 – 3.0.x | >= 3.10 |

The `compat` module detects the installed AGT version at import time and raises `RuntimeError` on unsupported versions.

## Installation

```bash
pip install aria-agentkit
```

## Quick Start

### Tool Call Interception via AuthZEN PDP

```python
from agent_os.integrations.base import CompositeInterceptor
from aria_agentkit import ARIAToolInterceptor

interceptor = ARIAToolInterceptor(
    pdp_url="https://pdp.example.com/access/v1/evaluation",
    pdp_application="my-agent-platform",
    token="my-bearer-token",
)

# Register with AGT's composite interceptor
composite = CompositeInterceptor()
composite.add(interceptor)
```

### Governance-Grade Audit Export

```python
from agent_os.audit_logger import GovernanceAuditLogger
from aria_agentkit import ARIAAuditBackend

audit = ARIAAuditBackend(
    receipt_vault_url="https://receipts.example.com",
)

logger = GovernanceAuditLogger()
logger.add_backend(audit)
```

### Policy Provider for Control Plane

```python
from aria_agentkit import ARIAPolicyProvider

provider = ARIAPolicyProvider(
    pdp_base_url="https://pdp.example.com",
    pdp_application="my-agent-platform",
    token="my-bearer-token",
)

policies = provider.get_policies(agent_id="agent-1")
```

### MCP Gateway Configuration

```python
from aria_agentkit.mcp.claude_desktop import claude_desktop_config
from aria_agentkit.mcp.sdk_session import mcp_session_params

# For Claude Desktop
config = claude_desktop_config(
    server_name="aria-gateway",
    gateway_url="https://mcp.example.com/v1/mcp",
    token="my-bearer-token",
)

# For MCP Python SDK
params = mcp_session_params(
    gateway_url="https://mcp.example.com/v1/mcp",
    token="my-bearer-token",
)
```

## Architecture

```
AGT Runtime                    aria-agentkit                 ARIA Services
┌─────────────────┐     ┌─────────────────────────┐    ┌──────────────────┐
│ PolicyEvaluator  │────>│ ARIAPolicyProvider      │───>│ AuthZEN PDP      │
│ ToolCallInter-   │────>│ ARIAToolInterceptor     │───>│                  │
│   ceptor chain   │     │                         │    │                  │
│ GovernanceAudit- │────>│ ARIAAuditBackend        │───>│ Receipt Vault    │
│   Logger         │     │   (outbox + hash chain) │    │                  │
│                  │     │                         │    │                  │
│                  │     │ MCP config emitters     │───>│ ARIA MCP Gateway │
└─────────────────┘     └─────────────────────────┘    └──────────────────┘
```

## AuthZEN Request Mapping

The interceptor maps AGT `ToolCallRequest` fields into OpenID AuthZEN 1.0 evaluation requests:

| AuthZEN Field | Value |
|---|---|
| `action.name` | `"tool.invoke"` (constant) |
| `resource.type` | `"mcp_tool"` |
| `resource.id` | `"mcp://{server_name}/{tool_name}"` |
| `subject.type` | `"agent"` |
| `subject.id` | `"auth:agent:agentmesh:{agent_id}"` |
| `context.call_id` | From `ToolCallRequest.call_id` |
| `context.original_args_hash` | SHA-256 of canonical arguments |
| `context.pdp_application` | Constructor parameter |

PDP `constraints` in the response are mapped to `ToolCallResult.modified_arguments` for parameter clamping.

## Audit Pipeline

The audit backend provides governance-grade export, not simple log shipping:

1. **Redaction** — Sensitive keys (`password`, `secret`, `token`, `api_key`, `credential`) are redacted recursively before persistence
2. **Hash Chaining** — Each receipt includes a `prev_hash` linking to the prior entry, producing a tamper-evident chain
3. **Idempotency** — Each receipt gets a unique idempotency key for deduplication
4. **Retry with Backoff** — Failed exports are retried with exponential backoff (capped at `max_backoff`)
5. **Dead Letter** — Persistently failing batches are routed to a configurable dead-letter callback

> **Note:** The outbox is in-memory. Unflushed entries are lost on process termination.
> Call `flush()` or `close()` before shutdown.

## Development

```bash
pip install -e ".[dev]"
pytest tests/ -v
ruff check src/ tests/
mypy src/
```

## License

MIT — see [LICENSE](LICENSE).
