Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.adrian.secureagentics.ai/llms.txt

Use this file to discover all available pages before exploring further.

Connecting an AI agent to Secureagentics involves two steps: registering the agent to obtain an agent ID, then instrumenting your agent code to send events as it runs. Once connected, Secureagentics monitors activity, enforces policies, and surfaces alerts in real time.

​
Prerequisites

  • A Secureagentics account with an active API key. Find your API key under Settings → API Keys.
  • The base URL for all API calls is https://api.secureagentics.ai/v1.
  • All requests require the header Authorization: Bearer <YOUR_API_KEY>.

​
Register an agent

Agent registration creates a persistent record in Secureagentics that all events from that agent are linked to. You register an agent once (typically at deploy time or application startup) and reuse the returned id for all subsequent event calls.

​
Registration request fields

FieldTypeRequiredDescription
namestringYesA unique name for this agent within your organization.
descriptionstringNoA human-readable description of what the agent does.
frameworkstringNoThe framework powering the agent, e.g. openai, langchain, custom.

​
Register your agent

1

Prepare your registration payload

Decide on a name that uniquely identifies this agent in its deployment environment. Use a naming convention such as <service>-<environment>, for example support-bot-production or data-extractor-staging.
2

Send the registration request

Call POST /v1/agents with your agent details.
import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://api.secureagentics.ai/v1"

response = requests.post(
    f"{BASE_URL}/agents",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "name": "support-bot-production",
        "description": "Customer support agent handling tier-1 queries",
        "framework": "openai",
    },
)

response.raise_for_status()
agent = response.json()
AGENT_ID = agent["id"]
print(f"Registered agent: {AGENT_ID}")
3

Store the agent ID

The response body contains an id field. Store this value — you will include it in every event call.
{
  "id": "agt_01hx9z3k2m4n5p6q7r8s9t0u",
  "name": "support-bot-production",
  "description": "Customer support agent handling tier-1 queries",
  "framework": "openai",
  "created_at": "2026-05-04T10:00:00Z"
}
Registration is idempotent by agent name within an environment. If you call POST /v1/agents with a name that already exists in your account, the API returns the existing agent record rather than creating a duplicate.

​
Send events from a running agent

Once your agent is registered, instrument it to send events to Secureagentics at each meaningful step — when it receives a prompt, generates a completion, calls a tool, or encounters an error.

​
Event request fields

FieldTypeRequiredDescription
typestringYesThe event type. See supported types below.
payloadobjectYesStructured data describing the event. Contents vary by type.
trace_idstringNoAn ID you assign to correlate related events into a single request trace.

​
Supported event types

TypeWhen to use
promptThe agent receives input from a user or upstream system.
completionThe agent produces a response or output.
tool_callThe agent invokes an external tool, function, or API.
errorAn exception or failure occurs during agent execution.

​
Send an event

1

Choose the correct event type

Emit an event at each step in your agent’s execution loop. For a simple prompt-response cycle, emit one prompt event when input arrives and one completion event when the response is ready.
2

Call the events endpoint

Send POST /v1/agents/{id}/events, replacing {id} with your registered agent ID.
import requests

API_KEY = "your_api_key_here"
AGENT_ID = "agt_01hx9z3k2m4n5p6q7r8s9t0u"
BASE_URL = "https://api.secureagentics.ai/v1"

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-Agent-ID": AGENT_ID,  # include for traceability
}

def send_event(event_type: str, payload: dict, trace_id: str = None):
    body = {"type": event_type, "payload": payload}
    if trace_id:
        body["trace_id"] = trace_id

    response = requests.post(
        f"{BASE_URL}/agents/{AGENT_ID}/events",
        headers=HEADERS,
        json=body,
    )
    response.raise_for_status()
    return response.json()

# Emit a prompt event
send_event(
    event_type="prompt",
    payload={"text": "How do I reset my password?", "user_id": "u_42"},
    trace_id="trace_abc123",
)

# Emit a completion event
send_event(
    event_type="completion",
    payload={"text": "To reset your password, go to...", "tokens_used": 120},
    trace_id="trace_abc123",
)
3

Handle the response

A successful event submission returns HTTP 201 with the stored event record.
{
  "id": "evt_09jk2l3m4n5o6p7q",
  "agent_id": "agt_01hx9z3k2m4n5p6q7r8s9t0u",
  "type": "prompt",
  "trace_id": "trace_abc123",
  "created_at": "2026-05-04T10:01:00Z"
}
If a policy is enforced and the event is blocked, the API returns HTTP 403 with a policy_violation error body. Your agent should handle this case and halt the offending action.

​
Best practices

Use a consistent naming scheme for agent names across environments. For example, suffix names with -production, -staging, or -development so each environment’s events are cleanly separated in the Secureagentics dashboard.
Include the agent ID in request headers. Add X-Agent-ID: <agent_id> to all event requests. This makes it easier to trace requests in your own infrastructure logs and correlate them with Secureagentics events. Handle registration errors gracefully. If POST /v1/agents returns a non-2xx response, log the error and consider whether to prevent the agent from starting. An unregistered agent cannot be monitored or governed. Use trace_id to link related events. Generate a unique trace_id (a UUID works well) at the start of each user request or agent run, and include it on every event emitted during that run. This powers end-to-end request tracing in the monitoring dashboard. Instrument all event types. Sending only prompt events gives you partial visibility. Emit completion, tool_call, and error events to get full coverage of your agent’s behavior and to enable anomaly detection. Register once, reuse the ID. Store your agent ID in environment configuration after the first registration. Do not register a new agent on every application startup — this creates duplicate records and pollutes your agent list.