agentauthlayer 0.1.3

Library-first authentication and authorization SDK for AI agents

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

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:

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.

2. 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=[],
)

3. 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)
• 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:

from agent_auth import ...

while the published package name is:

pip install agentauthlayer