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.

The custom integration lets you connect any AI agent to Secureagentics using plain HTTP requests. Use this approach when your agent is built on a framework not covered by a native integration, runs in a language other than Python or TypeScript, or follows a proprietary architecture. If a native integration exists for your framework (OpenAI, LangChain), prefer that — it requires less code. If not, the REST API gives you full flexibility.

​
Prerequisites

  • A Secureagentics account with an API key. Find your key in Settings → API Keys.
  • The ability to make outbound HTTPS requests from your agent’s runtime.

​
Steps

1

Register your agent

Send a POST /v1/agents request with "custom" as the framework value. You only need to do this once per agent.
curl --request POST \
  --url https://api.secureagentics.ai/v1/agents \
  --header "Authorization: Bearer YOUR_SECUREAGENTICS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "my-custom-agent",
    "framework": "custom",
    "description": "Bespoke retrieval-augmented generation pipeline"
  }'
Save the id from the response. All event submissions reference this ID.
{
  "id": "agt_01hx9z3k2m4p5q6r7s8t9u0v",
  "name": "my-custom-agent",
  "framework": "custom",
  "created_at": "2026-05-04T10:00:00Z"
}
2

Understand the event schema

Every event you send to POST /v1/agents/{id}/events must follow this structure:
FieldTypeRequiredDescription
typestringYesEvent type. One of prompt, completion, tool_call, error, custom.
payloadobjectYesArbitrary JSON object containing the event data.
trace_idstringNoA correlation ID you supply to group related events for a single request.
timestampstringNoISO 8601 timestamp. Defaults to the time Secureagentics receives the event.
Event types:
  • prompt — The input sent to an LLM.
  • completion — The output returned by an LLM.
  • tool_call — An external tool or function invoked by the agent.
  • error — An exception or failure in the agent pipeline.
  • custom — Any other event meaningful to your application.
The payload object has no enforced schema — you can include any fields that are useful for your monitoring needs. Secureagentics indexes common fields like model, prompt, response, and token_count automatically when present.
3

Send events

Post events to https://api.secureagentics.ai/v1/agents/{id}/events with your API key in the Authorization header.
import os
import uuid
import requests
from datetime import datetime, timezone

SECUREAGENTICS_API_KEY = os.environ["SECUREAGENTICS_API_KEY"]
AGENT_ID = os.environ["SECUREAGENTICS_AGENT_ID"]

def send_event(event_type: str, payload: dict, trace_id: str | None = None) -> None:
    body = {
        "type": event_type,
        "payload": payload,
        "timestamp": datetime.now(timezone.utc).isoformat(),
    }
    if trace_id:
        body["trace_id"] = trace_id

    response = requests.post(
        f"https://api.secureagentics.ai/v1/agents/{AGENT_ID}/events",
        headers={
            "Authorization": f"Bearer {SECUREAGENTICS_API_KEY}",
            "Content-Type": "application/json",
        },
        json=body,
        timeout=5,
    )
    response.raise_for_status()

# Example usage
trace_id = str(uuid.uuid4())

send_event(
    "prompt",
    {"model": "my-local-llm", "prompt": "Summarize this document.", "token_count": 42},
    trace_id=trace_id,
)

# ... call your LLM ...

send_event(
    "completion",
    {"model": "my-local-llm", "response": "Here is a summary.", "token_count": 18},
    trace_id=trace_id,
)
4

Batch events for efficiency

If your agent generates a high volume of events, use the batch endpoint to send multiple events in a single request. This reduces the number of outbound HTTP calls and helps you stay within rate limits.Send a POST request to https://api.secureagentics.ai/v1/agents/{id}/events/batch with a JSON array of event objects.
def send_events_batch(events: list[dict]) -> None:
    response = requests.post(
        f"https://api.secureagentics.ai/v1/agents/{AGENT_ID}/events/batch",
        headers={
            "Authorization": f"Bearer {SECUREAGENTICS_API_KEY}",
            "Content-Type": "application/json",
        },
        json=events,
        timeout=10,
    )
    response.raise_for_status()

# Example: send prompt and completion together
trace_id = str(uuid.uuid4())

send_events_batch([
    {
        "type": "prompt",
        "trace_id": trace_id,
        "payload": {"model": "my-local-llm", "prompt": "What is 2 + 2?", "token_count": 6},
    },
    {
        "type": "completion",
        "trace_id": trace_id,
        "payload": {"model": "my-local-llm", "response": "4", "token_count": 1},
    },
])
5

Handle errors

The Secureagentics API returns standard HTTP status codes. Handle these in your integration to avoid silent failures.
StatusMeaningAction
401Invalid or missing API keyCheck your Authorization header and verify the key is active.
404Agent ID not foundConfirm the agent_id matches a registered agent.
429Rate limit exceededBack off and retry. See the Retry-After response header.
Do not let Secureagentics API errors crash your agent. Wrap event-sending calls in error handling so that a network failure or a 429 response does not interrupt your agent’s primary task. Log failures locally so you can investigate missed events later.