Skip to content

Developer Guide

Integrate AI agents with AegisAI using the REST API, Python SDK, webhooks, and third-party framework connectors.

Integration Paths

flowchart LR
    A[Your Agent] --> B{Integration Method}
    B --> C[Python SDK]
    B --> D[REST API]
    B --> E[Webhooks]
    B --> F[LangChain / OpenAI]

    C --> G[AegisAI Platform]
    D --> G
    E --> G
    F --> G
Method Best For Auth
Python SDK Python agents, notebooks X-API-Key
REST API Any language, custom integrations X-API-Key or JWT
Prompt Guard Pre-LLM prompt validation X-API-Key
Webhooks Event-driven, non-Python agents HMAC signature
Integrations LangChain, OpenAI frameworks X-API-Key

Quick Integration

1. Get an API Key

Create a tenant or use an existing API key:

curl -X POST http://localhost:8000/api/v1/tenants \
  -H "X-Admin-Key: admin-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-org"}'

2. Register Your Agent

from aegisai.sdk import AegisAIClient

client = AegisAIClient(
    api_key="your-tenant-api-key",
    base_url="http://localhost:8000",
    agent_name="my-agent",
)

registration = await client.register()
print(f"Agent ID: {registration.id}")

3. Validate Prompts (Prompt Guard)

if not await client.guard.is_safe(user_prompt):
    result = await client.guard.validate(user_prompt)
    print("Blocked:", result["reasons"], result["score"])
    return

Middleware also protects POST /agents/{id}/chat|action|completions when ENABLE_GUARD=true. See Prompt Guard.

4. Check Policies Before Actions

decision = await client.check_policy(
    action="read_data",
    resource="customer_pii",
    context={"consent": True, "lawful_basis": "consent"},
)

if not decision.allowed:
    print(f"Blocked: {decision.reason}")
    if decision.required_approval:
        # Request HITL approval
        pass

5. Log Actions to Audit Trail

async with client.observe("query_database", "customers") as obs:
    obs.set_input({"query": "SELECT * FROM customers LIMIT 10"})
    result = await run_query()
    obs.set_output({"rows": len(result)})

Authentication

All API requests require authentication:

Header Value Use Case
X-API-Key Tenant or user API key Agent operations, SDK
Authorization Bearer <jwt> User management, dashboard
X-Admin-Key Admin provisioning key Tenant creation only
X-Webhook-Signature HMAC-SHA256 hex Webhook payloads

Core Workflow

sequenceDiagram
    participant Agent
    participant SDK as AegisAI SDK
    participant API as AegisAI API

    Agent->>SDK: register()
    SDK->>API: POST /agents/register
    API-->>SDK: agent_id

    Agent->>SDK: check_policy(action, resource)
    SDK->>API: POST /policies/check
    API-->>SDK: allowed, risk_score

    alt Allowed
        Agent->>Agent: Execute action
        Agent->>SDK: log_action(...)
        SDK->>API: POST /audit/log
    else Denied
        Agent->>Agent: Block or request HITL
    end

    Agent->>SDK: heartbeat()
    SDK->>API: POST /agents/{id}/heartbeat

Error Handling

Status Exception Action
401 UnauthorizedError Check API key
403 ForbiddenError Check role permissions
404 NotFoundError Verify resource ID
422 Validation error Fix request payload
500 APIError Check server logs 
from aegisai.sdk.exceptions import APIError, AgentNotRegisteredError

try:
    await client.log_action("read", "data")
except AgentNotRegisteredError:
    await client.register()
except APIError as e:
    print(f"API error {e.status_code}: {e}")

Sections

OpenAPI Documentation

Interactive API docs are available at runtime:

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc