Metadata-Version: 2.4
Name: agentauthlayer
Version: 0.1.3
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. First-time developer setup

For a fresh self-hosted deployment, complete the control plane setup before using `agentauth login`.

1. Start your Agent Auth deployment.
2. Open the UI in your browser.
3. Create the first super admin password.
4. Create your first project.
5. Then log in from the CLI.

Open the UI with:

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

Then 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
```

If the deployment has not been initialized yet, `agentauth login` will tell you to finish setup in the UI first.

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

`AGENT_AUTH_TOKEN` is typically a bearer token, often represented as a long JWT string.

Recommended usage:
- use `agentauth login` for local human developer workflows
- use `AGENT_AUTH_TOKEN` for CI, automation, or service-driven execution

If an env token expires, requests will fail until you replace it or log in again.
Avoid committing tokens into source control or long-lived shared `.env` files.

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
```
