SDK quickstart
2 minutes
Secure an AI agent with three lines of Python. No configuration needed. Risk levels resolve from the capability string.
Prerequisites
- AIM running at
http://localhost:3000(see Installation). - Python 3.8 or later.
Optional: run the bundled demo agent
The SDK ships with an interactive demo. Pair it with the AIM dashboard at localhost:3000/dashboard/agents to see actions land in the audit log.
unzip ~/Downloads/aim-sdk-python.zip
cd aim-sdk-python
pip install -e .
python demo_agent.py1
Download the SDK
The SDK comes pre-configured with credentials for your AIM instance. No API keys to manage.
- 1. Login to AIM at
http://localhost:3000. - 2. Go to Settings → SDK Download.
- 3. Click Download Python SDK.
- 4. Extract the archive and install in editable mode.
unzip ~/Downloads/aim-sdk-python.zip
cd aim-sdk-python
pip install -e .The SDK bundle includes signed credentials. No further configuration needed.
2
Register the agent
Create a Python file in the extracted SDK folder. One call to secure() generates the Ed25519 keypair, registers with AIM, and detects the agent framework from your imports.
from aim_sdk import secure
import langchain
# secure() detects the framework from imports
# (langchain, crewai, anthropic, openai),
# generates Ed25519 keys, registers with AIM,
# and stores credentials in the bundle.
agent = secure("my-first-agent")
# Or specify explicitly:
# from aim_sdk import secure, AgentType
# agent = secure("my-agent", agent_type=AgentType.CREWAI)
@agent.perform_action(capability="weather:fetch")
def fetch_weather(city):
return f"Weather in {city}: Sunny"Run it.
python my_agent.pyFramework detection. The SDK reads your Python imports to infer agent type.
langchain, crewai → frameworkanthropic, openai → LLM providerFrameworks take priority over LLM providers. If both langchain and anthropic are imported, the agent type is langchain.
3
Secure actions with decorators
Decorate each function that performs a capability. Risk level resolves from the capability string. Override when needed.
from aim_sdk import secure
agent = secure("my-first-agent")
# Risk level resolves from the capability string.
@agent.perform_action(capability="weather:fetch") # low
def fetch_weather(city):
"""Every call is verified, signed, and logged."""
return f"Weather in {city}: Sunny, 72F"
@agent.perform_action(capability="email:send") # high
def send_email(to, subject, body):
"""High-risk actions are flagged and monitored."""
print(f"Sending email to {to}: {subject}")
return True
@agent.perform_action(capability="db:delete") # high
def delete_record(table, id):
"""Delete actions are high risk."""
print(f"Deleting {id} from {table}")
return True
# Override when the auto-resolution is too permissive.
@agent.perform_action(capability="api:internal", risk_level="critical")
def internal_admin_call():
"""Internal API that needs critical-level monitoring."""
return admin_api.call()
# JIT access pauses execution until a human approves in the dashboard.
@agent.perform_action(capability="db:drop", jit_access=True) # critical
def drop_database(db_name):
print(f"Dropping database: {db_name}")
return True
result = fetch_weather("San Francisco")
print(result)
send_email("user@example.com", "Hello", "Test message")Risk-level resolution. Two lookup tables in
sdk/python/aim_sdk/risk_detector.py map capability strings to risk levels. When namespace and action disagree, the higher risk wins. Pass risk_level="critical" to override.| Source | Pattern | Resolves to |
|---|---|---|
| Namespace | payment:, admin:, system:, billing:, finance: | critical |
| Namespace | email:, notification:, sms:, user:, auth:, secret:, credential: | high |
| Namespace | db:, database:, file:, storage:, cache: | medium |
| Namespace | api:, weather:, search:, geocode:, translate:, time:, math:, util: | low |
| Action | :read, :fetch, :get, :list, :query, :view, :check, :validate | low |
| Action | :write, :update, :create, :modify, :save, :upload | medium |
| Action | :delete, :send, :execute, :run, :invoke, :export, :transfer | high |
| Action | :process, :refund, :charge, :approve, :drop, :truncate, :wipe, :terminate | critical |
Full pattern reference: Action Decorators Guide.
4
View activity in the dashboard
Open AIM at http://localhost:3000.
- Agents: the registered agent with its trust score.
- Activity: tracked actions with timestamps and outcomes.
- Audit Logs: the full audit trail for compliance.
Complete example
Copy this file into the extracted SDK folder. Risk levels resolve from the capability string in each decorator.
"""
AIM SDK quickstart example.
Run after downloading the SDK from the AIM dashboard.
"""
from aim_sdk import secure
agent = secure("weather-bot")
@agent.perform_action(capability="weather:fetch") # low
def get_weather(city: str) -> dict:
return {
"city": city,
"temperature": 72,
"condition": "Sunny"
}
@agent.perform_action(capability="db:read", resource="user_preferences") # low
def get_user_preferences(user_id: str) -> dict:
return {
"user_id": user_id,
"preferred_unit": "fahrenheit",
"notifications": True
}
@agent.perform_action(capability="notification:send") # high
def send_weather_alert(user_id: str, message: str) -> bool:
print(f"Sending to {user_id}: {message}")
return True
@agent.perform_action(capability="payment:charge") # critical
def charge_premium_subscription(user_id: str, amount: float) -> bool:
print(f"Charging {user_id}: ${amount}")
return True
# Override for an internal API that warrants critical-level monitoring.
@agent.perform_action(capability="api:internal", risk_level="critical")
def internal_admin_operation() -> dict:
return {"status": "ok"}
if __name__ == "__main__":
print("Weather Bot starting...")
weather = get_weather("San Francisco") # low
print(f"Weather: {weather}")
prefs = get_user_preferences("user_123") # low
print(f"User preferences: {prefs}")
send_weather_alert("user_123", f"It is {weather['temperature']}F.") # high
print("All actions completed and logged to AIM.")