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.

This guide walks you through registering an OpenAI-based agent with Secureagentics and instrumenting your completion calls to send events before and after each LLM interaction.

​
Prerequisites

  • A Secureagentics account with an API key. Find your key in Settings → API Keys.
  • An OpenAI API key.
  • Python 3.8+ or Node.js 18+ with the relevant packages installed.
pip install openai requests

​
Steps

1

Register your agent

Before sending events, register your agent with the Secureagentics API. This creates an agent record and returns an agent_id you will use in all subsequent event calls.
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-openai-agent",
    "framework": "openai",
    "description": "Customer support agent powered by GPT-4o"
  }'
The response includes an id field. Save this value — you will pass it as the agent_id when sending events.
{
  "id": "agt_01hx9z3k2m4p5q6r7s8t9u0v",
  "name": "my-openai-agent",
  "framework": "openai",
  "created_at": "2026-05-04T10:00:00Z"
}
2

Send a prompt event before the completion call

Before calling the OpenAI API, send a prompt event to Secureagentics. Include the model name, the prompt text, and an estimated token count.
import requests

def send_prompt_event(agent_id, api_key, model, prompt_text, token_count, trace_id=None):
    payload = {
        "type": "prompt",
        "payload": {
            "model": model,
            "prompt": prompt_text,
            "token_count": token_count,
        },
    }
    if trace_id:
        payload["trace_id"] = trace_id

    requests.post(
        f"https://api.secureagentics.ai/v1/agents/{agent_id}/events",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=5,
    )
3

Call the OpenAI API

Make your normal OpenAI completion call. Capture the response so you can forward it to Secureagentics in the next step.
4

Send a completion event after the response

After receiving the OpenAI response, send a completion event with the model name, response text, and token count from the usage object.
def send_completion_event(agent_id, api_key, model, response_text, token_count, trace_id=None):
    payload = {
        "type": "completion",
        "payload": {
            "model": model,
            "response": response_text,
            "token_count": token_count,
        },
    }
    if trace_id:
        payload["trace_id"] = trace_id

    requests.post(
        f"https://api.secureagentics.ai/v1/agents/{agent_id}/events",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=5,
    )
5

View events in the dashboard

Open the Secureagentics dashboard and navigate to Agents → your agent name → Events. You will see a chronological list of prompt and completion events with timestamps, token counts, and policy evaluation results.
Use the trace_id field to group a prompt event and its corresponding completion event together. This makes it easy to follow a single request end-to-end in the event log.

​
Complete examples

The examples below show a full instrumented OpenAI completion call from start to finish. 
import os
import uuid
import requests
from openai import OpenAI

SECUREAGENTICS_API_KEY = os.environ["SECUREAGENTICS_API_KEY"]
OPENAI_API_KEY = os.environ["OPENAI_API_KEY"]
AGENT_ID = os.environ["SECUREAGENTICS_AGENT_ID"]  # from registration step
MODEL = "gpt-4o"

openai_client = OpenAI(api_key=OPENAI_API_KEY)

def secureagentics_post(path, body):
    requests.post(
        f"https://api.secureagentics.ai/v1{path}",
        headers={
            "Authorization": f"Bearer {SECUREAGENTICS_API_KEY}",
            "Content-Type": "application/json",
        },
        json=body,
        timeout=5,
    )

def run_instrumented_completion(user_message: str) -> str:
    trace_id = str(uuid.uuid4())
    prompt_text = user_message

    # Send prompt event
    secureagentics_post(
        f"/agents/{AGENT_ID}/events",
        {
            "type": "prompt",
            "trace_id": trace_id,
            "payload": {
                "model": MODEL,
                "prompt": prompt_text,
                "token_count": len(prompt_text.split()),  # approximate
            },
        },
    )

    # Call OpenAI
    response = openai_client.chat.completions.create(
        model=MODEL,
        messages=[{"role": "user", "content": user_message}],
    )

    response_text = response.choices[0].message.content
    completion_tokens = response.usage.completion_tokens

    # Send completion event
    secureagentics_post(
        f"/agents/{AGENT_ID}/events",
        {
            "type": "completion",
            "trace_id": trace_id,
            "payload": {
                "model": MODEL,
                "response": response_text,
                "token_count": completion_tokens,
            },
        },
    )

    return response_text


if __name__ == "__main__":
    answer = run_instrumented_completion("What is the capital of France?")
    print(answer)
Store your SECUREAGENTICS_API_KEY, OPENAI_API_KEY, and SECUREAGENTICS_AGENT_ID as environment variables. Never hard-code credentials in your source code.