Metadata-Version: 2.4
Name: agentauthlayer
Version: 0.1.2
Summary: Library-first authentication and authorization SDK for AI agents
Author: Vaibhav Ahluwalia
License: MIT
Project-URL: Homepage, https://pypi.org/project/agentauthlayer/
Keywords: agents,auth,authorization,iam,security,sdk
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0
Requires-Dist: python-jose>=3.3.0

# agentauthlayer

Python SDK for integrating agent runtimes with the Agent Auth control plane.

`agentauthlayer` helps you:
- authenticate once and reuse local credentials
- register agents from code
- sync tool and capability definitions
- evaluate permissions against the control plane
- apply permission checks inside runtime functions

This package is the reusable SDK layer. It is intended for developers integrating Python agents, tools, and workflows with an Agent Auth deployment.

## Install

```bash
pip install agentauthlayer
```

## Quickstart

### 1. Log in once

```bash
agentauth login --base-url http://127.0.0.1:8002
```

This stores local credentials so your code can connect without manually pasting a token every time.

Useful follow-up commands:

```bash
agentauth whoami
agentauth logout
agentauth ui
```

### 2. Define tools and agents in code

```python
from agent_auth import register_tool, register_agent, require_permission

@register_tool(action="math.compute", description="Run approved math jobs")
@require_permission("math.compute", resource="math/basic")
def add(a: int, b: int, agent_id: str | None = None, role: str | None = None, context: dict | None = None):
    return a + b

register_agent(
    agent_id="math-agent",
    name="Math Agent",
    owner="you@company.com",
    role="research_agent",
    project_id="ai-platform",
    scopes=[],
)
```

### 3. Sync everything with one command

```bash
agentauth sync --module your_module_name
```

This imports the module, discovers registered tools and agents, syncs capability definitions, and creates agents through the control plane.

## SDK client usage

```python
from agent_auth import AuthAPIClient

client = AuthAPIClient()

agent = client.create_agent(
    agent_id="research-bot-01",
    name="Research Bot 01",
    owner="vaibhav@company.com",
    role="research_agent",
    scopes=[],
    project_id="ai-platform",
)

print(agent)
```

## Environment variables

If you prefer non-interactive configuration, the SDK also supports environment variables:

```bash
export AGENT_AUTH_URL=http://127.0.0.1:8002
export AGENT_AUTH_TOKEN=YOUR_ADMIN_OR_SERVICE_TOKEN
```

Resolution order used by `AuthAPIClient()`:
1. explicit constructor arguments
2. environment variables
3. stored local credentials from `agentauth login`

## Common tasks

### Sync tools manually

```python
client.sync_tools([
    {"action": "tool.search_web", "description": "Search the web"},
    {"action": "docs.read", "description": "Read protected docs"},
])
```

### Evaluate access

```python
decision = client.evaluate(
    principal_id="research-bot-01",
    action="tool.search_web",
    resource="web/*",
    role="research_agent",
)

print(decision)
```

### Fetch or delete an agent

```python
agent = client.get_agent("research-bot-01")
print(agent)

result = client.delete_agent("research-bot-01")
print(result)
```

CLI equivalent:

```bash
agentauth delete-agent research-bot-01
```

## Public package scope

This package provides:
- the Python SDK (`agent_auth`)
- CLI helpers for login, sync, and agent cleanup
- registry-based tool and agent sync
- permission evaluation helpers

It does not package the full control plane server or admin dashboard.

## Suitable use cases

- Python agent runtimes
- tool-based workflows
- service-to-control-plane integrations
- local development with stored credentials
- CI or automation using environment variables

## Requirements

- Python 3.10+
- access to a running Agent Auth control plane

## Notes

The import path remains:

```python
from agent_auth import ...
```

while the published package name is:

```bash
pip install agentauthlayer
```
