agentauthlayer 0.1.5

Library-first authentication and authorization SDK for AI agents

agentauthlayer

Unified SDK and local control plane package for Agent Auth.

agentauthlayer helps you:

• start a local Agent Auth backend and UI with one command
• 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 now ships as a unified developer install containing:

• the reusable Python SDK layer
• the local control plane backend runtime
• the packaged admin UI assets

Install

pip install agentauthlayer

Quickstart

1. Start the local control plane

For a local developer setup, start Agent Auth with one command:

agentauth up

This starts the packaged local control plane on http://127.0.0.1:8002 by default.

If you want a different port:

agentauth up --port 8014

2. First-time developer setup

For a fresh deployment:

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

Open the UI with:

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

Then log in once:

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:

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.

3. Define tools and agents in code

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="[e-mail]",
    role="research_agent",
    project_id="ai-platform",
    scopes=[],
)

4. Sync everything with one command

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

from agent_auth import AuthAPIClient

client = AuthAPIClient()

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

print(agent)

Environment variables

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

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

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

Evaluate access

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

print(decision)

Fetch or delete an agent

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

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

CLI equivalent:

agentauth delete-agent research-bot-01

Public package scope

This package provides:

• the Python SDK (agent_auth)
• local control plane startup via agentauth up
• packaged backend runtime (auth_app)
• packaged admin UI assets
• CLI helpers for login, sync, and agent cleanup
• registry-based tool and agent sync
• permission evaluation helpers

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 package naming model is:

• install name: agentauthlayer
• CLI: agentauth
• Python import namespace: agent_auth

The import path remains:

from agent_auth import ...

while the published package name is:

pip install agentauthlayer