Universal Interceptor SDKs

February 18, 2026 · View on GitHub

Monitor every AI agent, enforce Cedar policies at runtime, and gain full observability -- regardless of language or framework. Trusera ships three open-source SDKs that share a single design philosophy: intercept, evaluate, report.

	Python	TypeScript	Go
Repository	trusera-agent-sdk	trusera-sdk-js	trusera-sdk-go
Package	`trusera-sdk` (PyPI)	`trusera-sdk` (npm)	`github.com/Trusera/ai-bom/trusera-sdk-go`
License	Apache 2.0	Apache 2.0	Apache 2.0

Overview
Feature Comparison
Architecture
Quick Start
Integration Guides for Top 10 Agent Frameworks
Enforcement Modes
Event Types Reference
Configuration Reference
Performance
Migration Guide

1. Overview

AI agents make autonomous decisions -- calling LLMs, invoking tools, reading databases, and hitting third-party APIs. Without observability, you are flying blind. Without enforcement, you have no guardrails.

The Trusera Interceptor SDK family solves both problems:

Intercept every outbound call your agent makes (HTTP requests, LLM invocations, tool calls, file writes, data access, and decision points).
Evaluate each action against Cedar policies -- the same policy language used by AWS Verified Permissions -- in real time.
Report a structured event stream to the Trusera platform for dashboards, alerts, compliance audits, and forensic analysis.

All three SDKs are designed around the same core concepts:

Concept	Description
Client	Authenticated connection to the Trusera API. Handles batching and flushing.
Interceptor	Language-specific hook that transparently captures outbound calls.
Event	A structured record of a single agent action (tool call, LLM invoke, etc.).
Enforcement Mode	How policy violations are handled: `log`, `warn`, or `block`.
Agent Registration	One-time registration that ties events to a named agent identity.

Choose the SDK that matches your agent's language:

Python SDK -- Best for LangChain, CrewAI, AutoGen, LlamaIndex, Semantic Kernel, and any Python-based agent.
TypeScript SDK -- Best for LangChain.js, Vercel AI SDK, OpenAI Node.js SDK, and any Node.js/Bun agent.
Go SDK -- Best for custom Go agents, microservices, and high-performance infrastructure agents.

2. Feature Comparison

Feature	Python	TypeScript	Go
Package name	`trusera-sdk`	`trusera-sdk`	`trusera-sdk-go`
Install command	`pip install trusera-sdk`	`npm install trusera-sdk`	`go get github.com/Trusera/ai-bom/trusera-sdk-go`
HTTP Interception	`@monitor` decorator	`fetch` + `axios` + `undici`	`http.RoundTripper` wrapper
LangChain Integration	`TruseraCallbackHandler`	`TruseraLangChainHandler`	--
CrewAI Integration	`TruseraCrewCallback` (StepCallback)	--	--
AutoGen Integration	`TruseraAutoGenHook` (MessageHook)	--	--
Enforcement Modes	`log` / `warn` / `block`	`log` / `warn` / `block`	`log` / `warn` / `block`
Event Batching	Thread-based queue	Timer-based queue	Goroutine-based queue
Async Support	`asyncio` native	Native `Promise` / `async-await`	Goroutines
Module Format	--	ESM + CJS (dual output via tsup)	--
External Dependencies	`httpx`	None (native `fetch`); optional `axios`, `undici`	None (stdlib only)
Min Runtime	Python 3.9+	Node.js 18+	Go 1.21+
Type Safety	Type hints (mypy)	Full TypeScript generics	Static typing
Context Manager	`with` statement	--	`defer client.Close()`
Global Intercept	`set_default_client()`	`interceptor.install()`	`trusera.InterceptDefault()`
Exclude Patterns	--	Regex patterns	String patterns
Block Patterns	--	--	String patterns
Agent Registration	`client.register_agent()`	`client.registerAgent()`	`client.RegisterAgent()`
Manual Flush	`client.flush()`	`await client.flush()`	`client.Flush()`
Graceful Shutdown	`client.close()`	`await client.close()`	`client.Close()`
Thread/Concurrency Safe	Yes (threading lock)	Yes (single-threaded + async)	Yes (mutex + goroutines)

3. Architecture

All three SDKs follow the same layered architecture. The interceptor sits between your agent code and the outside world, capturing events and optionally enforcing Cedar policies before requests leave the process.

                        Your Application
                 ┌─────────────────────────────┐
                 │                             │
                 │   ┌───────────────────┐     │
                 │   │   AI Agent Code   │     │
                 │   │  (LangChain,      │     │
                 │   │   CrewAI, custom)  │     │
                 │   └────────┬──────────┘     │
                 │            │                │
                 │            │  function call │
                 │            ▼                │
                 │   ┌───────────────────┐     │
                 │   │  Trusera SDK      │     │
                 │   │  Interceptor      │     │
                 │   │                   │     │
                 │   │  1. Capture args  │     │
                 │   │  2. Evaluate      │     │
                 │   │     Cedar policy  │     │
                 │   │  3. Enforce       │     │
                 │   │     (log/warn/    │     │
                 │   │      block)       │     │
                 │   │  4. Queue event   │     │
                 │   └───┬─────────┬─────┘     │
                 │       │         │            │
                 │       │ pass    │ events     │
                 │       │ through │ (batched)  │
                 │       ▼         ▼            │
                 └───────┼─────────┼────────────┘
                         │         │
              ┌──────────┘         └──────────┐
              ▼                               ▼
     ┌─────────────────┐            ┌─────────────────┐
     │  External APIs  │            │  Trusera API    │
     │  & Tools        │            │                 │
     │                 │            │  ┌───────────┐  │
     │  - OpenAI       │            │  │  Cedar    │  │
     │  - Anthropic    │            │  │  Policy   │  │
     │  - Databases    │            │  │  Engine   │  │
     │  - File systems │            │  └───────────┘  │
     │  - Webhooks     │            │                 │
     └─────────────────┘            │  ┌───────────┐  │
                                    │  │ Dashboard │  │
                                    │  │ & Alerts  │  │
                                    │  └───────────┘  │
                                    └─────────────────┘

Interception Mechanisms by Language

Python -- The @monitor decorator wraps functions at definition time. When a decorated function is called, the SDK captures input arguments, measures execution time, records the return value (or exception), and queues an event. A background thread flushes events to the Trusera API at configurable intervals.

TypeScript -- The TruseraInterceptor patches up to three HTTP libraries automatically: native fetch (always available), axios (via request/response interceptors), and undici (via monkey-patching request and fetch). Libraries are detected at install-time using require() -- if absent, they are silently skipped. Each intercepted call captures URL, method, headers, and body; after the real request completes the SDK records the response status and queues an event. A setInterval timer drives periodic flushes. The SDK ships as both ESM and CJS (built with tsup) so it works in any Node.js or Bun environment.

Go -- The SDK provides a custom http.RoundTripper that wraps the standard http.Transport. Every request passing through the wrapped http.Client is intercepted, measured, and recorded. A background goroutine flushes the event buffer on a ticker.

4. Quick Start

Python

from trusera_sdk import TruseraClient, Event, EventType

client = TruseraClient(api_key="tsk_your_api_key")
client.register_agent("my-agent", "custom")

client.track(Event(
    type=EventType.TOOL_CALL,
    name="web_search",
    payload={"query": "latest AI news"}
))

client.close()

TypeScript

import { TruseraClient, TruseraInterceptor } from "trusera-sdk";

const client = new TruseraClient({
  apiKey: "tsk_your_api_key",
  agentId: "my-agent",
});

const interceptor = new TruseraInterceptor();
interceptor.install(client, { enforcement: "log" });

// All fetch() calls are now tracked automatically
await fetch("https://api.openai.com/v1/chat/completions", {
  method: "POST",
  body: JSON.stringify({ model: "gpt-4", messages: [] }),
});

await client.close();
interceptor.uninstall();

Go

package main

import (
    "net/http"
    "github.com/Trusera/ai-bom/trusera-sdk-go"
)

func main() {
    client := trusera.NewClient("tsk_your_api_key")
    defer client.Close()

    client.RegisterAgent("my-agent", "custom")

    httpClient := trusera.WrapHTTPClient(&http.Client{}, client, trusera.InterceptorOptions{
        Enforcement: trusera.ModeLog,
    })

    // All requests through httpClient are tracked automatically
    resp, _ := httpClient.Get("https://api.openai.com/v1/models")
    defer resp.Body.Close()
}

5. Integration Guides for Top 10 Agent Frameworks

5.1 LangChain (Python)

SDK: Python (trusera-sdk[langchain])

LangChain's callback system provides hooks for every LLM call, tool execution, and chain step. The TruseraCallbackHandler plugs directly into these hooks.

from langchain.llms import OpenAI
from langchain.agents import initialize_agent, Tool
from trusera_sdk import TruseraClient
from trusera_sdk.integrations.langchain import TruseraCallbackHandler

client = TruseraClient(api_key="tsk_your_api_key")
client.register_agent("langchain-agent", "langchain")
handler = TruseraCallbackHandler(client)

llm = OpenAI(callbacks=[handler])
agent = initialize_agent(
    tools=[
        Tool(name="search", func=search_fn, description="Search the web"),
    ],
    llm=llm,
    callbacks=[handler],
)

# Every LLM call, tool execution, and chain step is tracked
agent.run("What are the top AI security risks?")
client.close()

What gets tracked: LLM_INVOKE for each model call, TOOL_CALL for each tool execution, DECISION for chain-of-thought steps.

5.2 LangChain.js (Node.js)

SDK: TypeScript (trusera-sdk)

The TypeScript SDK provides a TruseraLangChainHandler that implements the LangChain.js BaseCallbackHandler interface.

import { ChatOpenAI } from "langchain/chat_models/openai";
import { TruseraClient, TruseraLangChainHandler } from "trusera-sdk";

const client = new TruseraClient({ apiKey: "tsk_your_api_key" });
const handler = new TruseraLangChainHandler(client);

const model = new ChatOpenAI({
  callbacks: [handler],
});

await model.invoke("What are the top AI security risks?");
await client.close();

With Cedar Policy Enforcement:

The handler supports optional Cedar policy enforcement for tool and LLM calls. Pass enforcement and a cedarEvaluator to activate runtime policy checks:

import {
  TruseraClient,
  TruseraLangChainHandler,
  CedarEvaluator,
} from "trusera-sdk";

const evaluator = new CedarEvaluator();
await evaluator.loadPolicy(`
  forbid (principal, action == Action::"*", resource)
  when { resource.hostname == "langchain" };
`);

const handler = new TruseraLangChainHandler(client, {
  enforcement: "block", // or "warn" or "log"
  cedarEvaluator: evaluator,
});

// In block mode, denied tool/LLM calls throw:
// Error: [Trusera] Policy violation: tool search denied - ...

What gets tracked: Same event types as the Python LangChain integration -- LLM_INVOKE, TOOL_CALL, and DECISION events. When enforcement is active, POLICY_VIOLATION events are also tracked for denied actions.

5.3 CrewAI

SDK: Python (trusera-sdk[crewai])

CrewAI uses a step callback pattern. The TruseraCrewCallback wraps this to capture crew execution, agent delegation, and task completion.

from crewai import Crew, Agent, Task
from trusera_sdk import TruseraClient
from trusera_sdk.integrations.crewai import TruseraCrewCallback

client = TruseraClient(api_key="tsk_your_api_key")
client.register_agent("crew-agent", "crewai")
callback = TruseraCrewCallback(client)

researcher = Agent(role="Researcher", goal="Research AI trends")
writer = Agent(role="Writer", goal="Write reports")

task = Task(description="Research and write about AI trends", agent=researcher)

crew = Crew(
    agents=[researcher, writer],
    tasks=[task],
    step_callback=callback.step_callback,
)

result = crew.kickoff()
client.close()

What gets tracked: DECISION for each crew step, TOOL_CALL for agent tool use, LLM_INVOKE for underlying model calls.

5.4 AutoGen

SDK: Python (trusera-sdk[autogen])

AutoGen's hook system lets you intercept messages between agents. The TruseraAutoGenHook captures all inter-agent communication and tool use.

import autogen
from trusera_sdk import TruseraClient
from trusera_sdk.integrations.autogen import TruseraAutoGenHook

client = TruseraClient(api_key="tsk_your_api_key")
client.register_agent("autogen-agent", "autogen")
hook = TruseraAutoGenHook(client)

assistant = autogen.AssistantAgent(
    name="assistant",
    llm_config={"model": "gpt-4"},
)
user_proxy = autogen.UserProxyAgent(name="user")

# Register hook for message tracking
hook.setup_agent(assistant)

user_proxy.initiate_chat(assistant, message="Analyze this data")
client.close()

What gets tracked: LLM_INVOKE for each model call, DECISION for agent message routing, TOOL_CALL for code execution and function calls.

5.5 LlamaIndex

SDK: Python (trusera-sdk)

LlamaIndex does not have a dedicated integration module, but the @monitor decorator works perfectly with LlamaIndex query engines and retrievers.

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from trusera_sdk import TruseraClient, monitor, set_default_client, EventType

client = TruseraClient(api_key="tsk_your_api_key")
client.register_agent("llamaindex-agent", "llamaindex")
set_default_client(client)

documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)

@monitor(event_type=EventType.DATA_ACCESS)
def query_index(question: str) -> str:
    query_engine = index.as_query_engine()
    response = query_engine.query(question)
    return str(response)

@monitor(event_type=EventType.LLM_INVOKE, name="llamaindex_query")
def ask(question: str) -> str:
    return query_index(question)

result = ask("What are the key findings?")
client.close()

What gets tracked: DATA_ACCESS for index queries, LLM_INVOKE for the top-level question-answering call.

5.6 Semantic Kernel (Python)

SDK: Python (trusera-sdk)

Microsoft Semantic Kernel exposes functions as plugins. Wrap plugin functions with @monitor to capture every kernel invocation.

import semantic_kernel as sk
from trusera_sdk import TruseraClient, monitor, set_default_client, EventType

client = TruseraClient(api_key="tsk_your_api_key")
client.register_agent("sk-agent", "semantic-kernel")
set_default_client(client)

kernel = sk.Kernel()

@monitor(event_type=EventType.TOOL_CALL)
def search_web(query: str) -> str:
    # Your search implementation
    return "Search results for: " + query

@monitor(event_type=EventType.LLM_INVOKE)
async def invoke_kernel(prompt: str) -> str:
    result = await kernel.invoke_prompt(prompt)
    return str(result)

result = await invoke_kernel("Summarize recent AI security papers")
client.close()

What gets tracked: TOOL_CALL for plugin function invocations, LLM_INVOKE for kernel prompt calls.

5.7 OpenAI Agents SDK

SDK: Python (trusera-sdk) or TypeScript (trusera-sdk)

The OpenAI Agents SDK can be instrumented from either language. Use the @monitor decorator in Python or the fetch interceptor in TypeScript.

Python

from agents import Agent, Runner
from trusera_sdk import TruseraClient, monitor, set_default_client, EventType

client = TruseraClient(api_key="tsk_your_api_key")
client.register_agent("openai-agent", "openai-agents-sdk")
set_default_client(client)

@monitor(event_type=EventType.TOOL_CALL)
def get_weather(city: str) -> str:
    return f"72F in {city}"

agent = Agent(
    name="weather-assistant",
    instructions="You help with weather queries.",
    tools=[get_weather],
)

result = Runner.run_sync(agent, "What is the weather in SF?")
client.close()

TypeScript

import { TruseraClient, TruseraInterceptor } from "trusera-sdk";

const client = new TruseraClient({
  apiKey: "tsk_your_api_key",
  agentId: "openai-agent",
});

const interceptor = new TruseraInterceptor();
interceptor.install(client, { enforcement: "log" });

// The OpenAI Agents SDK uses fetch internally --
// all API calls are captured automatically
import { Agent } from "@openai/agents";

const agent = new Agent({ name: "assistant" });
const result = await agent.run("What is the weather in SF?");

await client.close();
interceptor.uninstall();

5.8 Vercel AI SDK

SDK: TypeScript (trusera-sdk)

The Vercel AI SDK uses fetch internally for all model calls. The Trusera interceptor captures these transparently.

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { TruseraClient, TruseraInterceptor } from "trusera-sdk";

const client = new TruseraClient({
  apiKey: "tsk_your_api_key",
  agentId: "vercel-ai-agent",
});

const interceptor = new TruseraInterceptor();
interceptor.install(client, {
  enforcement: "warn",
  excludePatterns: ["^http://localhost.*"],
});

// All model calls through the Vercel AI SDK are captured
const { text } = await generateText({
  model: openai("gpt-4"),
  prompt: "Explain AI agent security in one paragraph.",
});

console.log(text);

await client.close();
interceptor.uninstall();

What gets tracked: API_CALL events for every outbound HTTP request to the model provider, with URL, method, status code, and latency.

5.9 Custom Go Agents

SDK: Go (trusera-sdk-go)

For Go agents built from scratch, wrap your http.Client and use manual event tracking for non-HTTP actions.

package main

import (
    "fmt"
    "net/http"
    "github.com/Trusera/ai-bom/trusera-sdk-go"
)

func main() {
    truseraClient := trusera.NewClient("tsk_your_api_key",
        trusera.WithAgentID("go-agent"),
    )
    defer truseraClient.Close()

    truseraClient.RegisterAgent("go-agent", "custom")

    // Wrap HTTP client -- all outbound requests are tracked
    httpClient := trusera.WrapHTTPClient(&http.Client{}, truseraClient, trusera.InterceptorOptions{
        Enforcement:    trusera.ModeBlock,
        BlockPatterns:  []string{"malicious.com"},
        ExcludePatterns: []string{"api.trusera.io", "localhost"},
    })

    // HTTP calls are auto-tracked
    resp, err := httpClient.Get("https://api.openai.com/v1/models")
    if err != nil {
        fmt.Println("Blocked or failed:", err)
        return
    }
    defer resp.Body.Close()

    // Track non-HTTP actions manually
    event := trusera.NewEvent(trusera.EventDecision, "route_selection").
        WithPayload("selected_route", "api_v2").
        WithPayload("confidence", 0.92)
    truseraClient.Track(event)
}

5.10 Custom Python Agents

SDK: Python (trusera-sdk)

For custom Python agents that do not use a framework, the @monitor decorator is the recommended approach.

from trusera_sdk import TruseraClient, monitor, set_default_client, EventType
import httpx

client = TruseraClient(api_key="tsk_your_api_key")
client.register_agent("custom-agent", "custom")
set_default_client(client)

@monitor(event_type=EventType.LLM_INVOKE, name="call_openai")
def call_openai(prompt: str) -> str:
    response = httpx.post(
        "https://api.openai.com/v1/chat/completions",
        json={"model": "gpt-4", "messages": [{"role": "user", "content": prompt}]},
        headers={"Authorization": "Bearer sk-..."},
    )
    return response.json()["choices"][0]["message"]["content"]

@monitor(event_type=EventType.TOOL_CALL, name="search_db")
def search_database(query: str) -> list[dict]:
    # Your database logic
    return [{"id": 1, "title": "Result"}]

@monitor(event_type=EventType.DECISION, name="agent_loop")
def agent_step(user_input: str) -> str:
    context = search_database(user_input)
    prompt = f"Context: {context}\nQuestion: {user_input}"
    return call_openai(prompt)

answer = agent_step("What are our top vulnerabilities?")
print(answer)
client.close()

What gets tracked: LLM_INVOKE for every OpenAI call, TOOL_CALL for every database search, DECISION for each agent loop iteration -- all with timing, input arguments, and return values.

6. Enforcement Modes

All three SDKs support three enforcement modes that control what happens when a policy violation is detected.

6.1 Log Mode (Default)

Events are recorded silently. No output to the console, no exceptions thrown, no requests blocked. This is the safest mode for initial rollout.

When to use: Development, staging, initial production deployment, audit-only compliance.

Python

# Log mode is the default -- no configuration needed
client = TruseraClient(api_key="tsk_your_api_key")

TypeScript

interceptor.install(client, { enforcement: "log" });
// fetch("https://restricted-api.com") -> request proceeds, event recorded silently

Go

opts := trusera.InterceptorOptions{
    Enforcement: trusera.ModeLog,
}
// httpClient.Get("https://restricted-api.com") -> request proceeds, event recorded

6.2 Warn Mode

Events are recorded and a warning is emitted. In Python this logs a warning, in TypeScript it prints to console.warn, in Go it writes to log.Printf. Requests are NOT blocked.

When to use: Pre-production hardening, gradual policy rollout, alerting teams to violations without breaking workflows.

Python

# Warning appears in logs:
# [Trusera] WARN: Policy violation detected for tool_call "restricted_api"

TypeScript

interceptor.install(client, { enforcement: "warn" });
// Console output: [Trusera] Policy violation (allowed): Unauthorized API access

Go

opts := trusera.InterceptorOptions{
    Enforcement: trusera.ModeWarn,
    BlockPatterns: []string{"suspicious.com"},
}
// Log output: [Trusera] WARN: request to suspicious.com matched block pattern
// Request proceeds normally

6.3 Block Mode

Violations cause the request to fail. In Python an exception is raised, in TypeScript an Error is thrown, in Go the HTTP response is replaced with a synthetic 403. This is the strongest enforcement mode.

When to use: Production enforcement, compliance-critical workloads, when you are confident your policies are correct.

Python

# Raises: trusera_sdk.PolicyViolationError: Blocked by policy: unauthorized_data_access

TypeScript

interceptor.install(client, { enforcement: "block" });
try {
  await fetch("https://restricted-api.com/data");
} catch (err) {
  // Error: [Trusera] Policy violation: Unauthorized API access
  console.error("Blocked:", err.message);
}

Go

opts := trusera.InterceptorOptions{
    Enforcement: trusera.ModeBlock,
    BlockPatterns: []string{"malicious.com"},
}
httpClient := trusera.WrapHTTPClient(&http.Client{}, truseraClient, opts)

resp, err := httpClient.Get("https://malicious.com/exfiltrate")
// err != nil: request blocked by Trusera policy

Enforcement Mode Summary

Mode	Logs Event	Console Output	Blocks Request	Use Case
`log`	Yes	No	No	Audit, development
`warn`	Yes	Yes (warning)	No	Staging, gradual rollout
`block`	Yes	Yes (error)	Yes	Production enforcement

7. Event Types Reference

All three SDKs share the same six event types. These provide a consistent schema across languages, making it possible to query and visualize events from Python, TypeScript, and Go agents in a single Trusera dashboard.

7.1 TOOL_CALL

Records a tool or function invocation by the agent.

Field	Type	Description
`type`	`string`	`"tool_call"`
`name`	`string`	Tool identifier (e.g., `"web_search"`, `"calculator"`)
`payload`	`object`	Input arguments and parameters
`metadata`	`object`	Duration, status, framework-specific data

Example Payload:

{
  "type": "tool_call",
  "name": "web_search",
  "payload": {
    "query": "AI security best practices",
    "results_count": 10
  },
  "metadata": {
    "duration_ms": 250,
    "status": "success"
  }
}

7.2 LLM_INVOKE

Records an LLM inference call.

Field	Type	Description
`type`	`string`	`"llm_invoke"`
`name`	`string`	Model identifier (e.g., `"gpt-4"`, `"claude-3"`)
`payload`	`object`	Model, tokens, temperature, prompt summary
`metadata`	`object`	Latency, provider, cost estimate

Example Payload:

{
  "type": "llm_invoke",
  "name": "openai.gpt4",
  "payload": {
    "model": "gpt-4",
    "prompt_tokens": 150,
    "completion_tokens": 75,
    "temperature": 0.7
  },
  "metadata": {
    "duration_ms": 1200,
    "provider": "openai"
  }
}

7.3 DATA_ACCESS

Records a data read or write operation.

Field	Type	Description
`type`	`string`	`"data_access"`
`name`	`string`	Data source identifier (e.g., `"database.users.read"`)
`payload`	`object`	Query, table, operation type, row count
`metadata`	`object`	Duration, data classification

Example Payload:

{
  "type": "data_access",
  "name": "database.users.read",
  "payload": {
    "table": "users",
    "query": "SELECT * FROM users WHERE role = 'admin'",
    "rows_returned": 42
  },
  "metadata": {
    "duration_ms": 15,
    "classification": "pii"
  }
}

7.4 API_CALL

Records an outbound HTTP API request. This event type is typically generated automatically by the HTTP interceptor.

Field	Type	Description
`type`	`string`	`"api_call"`
`name`	`string`	HTTP method and URL (e.g., `"POST https://api.stripe.com/v1/charges"`)
`payload`	`object`	URL, method, status code, request/response size
`metadata`	`object`	Latency, headers (redacted), TLS info

Example Payload:

{
  "type": "api_call",
  "name": "POST https://api.stripe.com/v1/charges",
  "payload": {
    "url": "https://api.stripe.com/v1/charges",
    "method": "POST",
    "status_code": 200,
    "response_size_bytes": 1524
  },
  "metadata": {
    "duration_ms": 340,
    "tls_version": "1.3"
  }
}

7.5 FILE_WRITE

Records a file system write operation.

Field	Type	Description
`type`	`string`	`"file_write"`
`name`	`string`	Operation identifier (e.g., `"save_report"`)
`payload`	`object`	File path, size, content type
`metadata`	`object`	Duration, permissions

Example Payload:

{
  "type": "file_write",
  "name": "save_report",
  "payload": {
    "path": "/tmp/report.pdf",
    "size_bytes": 1024,
    "content_type": "application/pdf"
  },
  "metadata": {
    "duration_ms": 5
  }
}

7.6 DECISION

Records an agent decision point or reasoning step.

Field	Type	Description
`type`	`string`	`"decision"`
`name`	`string`	Decision identifier (e.g., `"approve_transaction"`)
`payload`	`object`	Confidence score, reasoning, selected action
`metadata`	`object`	Context, alternatives considered

Example Payload:

{
  "type": "decision",
  "name": "approve_transaction",
  "payload": {
    "confidence": 0.95,
    "reasoning": "All fraud checks passed",
    "selected_action": "approve"
  },
  "metadata": {
    "alternatives": ["flag_for_review", "reject"],
    "context": "transaction_id=txn_abc123"
  }
}

8. Configuration Reference

8.1 Environment Variables

All three SDKs respect the same environment variables, providing a consistent configuration experience across languages.

Variable	Description	Default
`TRUSERA_API_KEY`	API key for authentication	(required)
`TRUSERA_API_URL`	Base URL for the Trusera API	`https://api.trusera.io`

export TRUSERA_API_KEY=tsk_your_api_key
export TRUSERA_API_URL=https://api.trusera.io

8.2 Programmatic Configuration

Python

client = TruseraClient(
    api_key="tsk_your_api_key",         # Required. Also reads TRUSERA_API_KEY
    base_url="https://api.trusera.io",  # API endpoint
    flush_interval=5.0,                  # Seconds between auto-flushes
    batch_size=100,                      # Max events per batch
    timeout=10.0,                        # HTTP request timeout (seconds)
)

Parameter	Type	Default	Description
`api_key`	`str`	env `TRUSERA_API_KEY`	Authentication key
`base_url`	`str`	`https://api.trusera.dev`	API base URL
`flush_interval`	`float`	`5.0`	Seconds between auto-flushes
`batch_size`	`int`	`100`	Maximum events per batch
`timeout`	`float`	`10.0`	HTTP timeout in seconds

TypeScript

const client = new TruseraClient({
  apiKey: "tsk_your_api_key",       // Required. Also reads TRUSERA_API_KEY
  baseUrl: "https://api.trusera.io", // API endpoint
  agentId: "my-agent",              // Pre-registered agent ID
  flushInterval: 5000,              // Milliseconds between auto-flushes
  batchSize: 100,                   // Max events per batch
  debug: false,                     // Enable debug logging
});

Parameter	Type	Default	Description
`apiKey`	`string`	env `TRUSERA_API_KEY`	Authentication key
`baseUrl`	`string`	`https://api.trusera.io`	API base URL
`agentId`	`string`	`undefined`	Pre-registered agent ID
`flushInterval`	`number`	`5000`	Milliseconds between flushes
`batchSize`	`number`	`100`	Maximum events per batch
`debug`	`boolean`	`false`	Enable debug logging

Interceptor Options:

Parameter	Type	Default	Description
`enforcement`	`"log" \| "warn" \| "block"`	`"log"`	Violation handling mode
`policyUrl`	`string`	`undefined`	Cedar policy service URL
`excludePatterns`	`string[]`	`[]`	URL regex patterns to skip
`debug`	`boolean`	`false`	Enable debug logging

Go

client := trusera.NewClient("tsk_your_api_key",
    trusera.WithBaseURL("https://api.trusera.io"),
    trusera.WithAgentID("my-agent"),
    trusera.WithFlushInterval(60 * time.Second),
    trusera.WithBatchSize(200),
)

Option Function	Type	Default	Description
`WithBaseURL(url)`	`string`	env `TRUSERA_API_URL` or `https://api.trusera.io`	API base URL
`WithAgentID(id)`	`string`	`""`	Pre-registered agent ID
`WithFlushInterval(d)`	`time.Duration`	`5s`	Duration between flushes
`WithBatchSize(n)`	`int`	`100`	Maximum events per batch

Environment Variable Fallbacks: If the apiKey argument is empty, NewClient reads TRUSERA_API_KEY. The default base URL is read from TRUSERA_API_URL (falling back to https://api.trusera.io). Explicit WithBaseURL() overrides the environment variable.

Interceptor Options:

Field	Type	Default	Description
`Enforcement`	`Mode`	`ModeLog`	`ModeLog`, `ModeWarn`, or `ModeBlock`
`ExcludePatterns`	`[]string`	`nil`	URL patterns to skip
`BlockPatterns`	`[]string`	`nil`	URL patterns that trigger enforcement

9. Performance

The SDKs are designed to add negligible overhead to your agent's execution. Here are the key design principles and benchmarks.

9.1 Non-Blocking by Default

Event tracking (track() / Track()) is always non-blocking. Events are placed in an in-memory buffer and flushed asynchronously:

SDK	Buffer Mechanism	Flush Trigger
Python	`queue.Queue` + background `threading.Thread`	Timer (default 5s) or batch size (default 100)
TypeScript	`Array` + `setInterval`	Timer (default 5000ms) or batch size (default 100)
Go	`[]Event` + `sync.Mutex` + background goroutine	`time.Ticker` (default 5s) or batch size (default 100)

9.2 Overhead

Operation	Typical Overhead
`track()` call	< 1 microsecond (buffer append)
HTTP interception (per request)	< 0.5 ms (timestamp + event creation)
Batch flush (100 events)	10-50 ms (single HTTP POST to Trusera API)

9.3 Batching Strategy

Events are accumulated in memory and sent in batches to minimize network round trips. A flush occurs when either condition is met:

The batch buffer reaches batch_size events (default: 100).
The flush timer fires (default: every 5 seconds).

On shutdown (close() / Close()), a final flush sends any remaining events.

9.4 Failure Handling

If a flush fails (network error, API timeout), the SDKs handle it gracefully:

Python: Logs the error via logging.warning(), discards the batch, continues.
TypeScript: Logs via console.warn(), retries once, then discards.
Go: Logs via log.Printf(), discards the batch, continues.

The SDK will never crash your application due to a telemetry failure. Agent execution always takes priority.

9.5 Memory Footprint

Each event consumes approximately 200-500 bytes in memory. With the default batch size of 100, the maximum buffer size before flush is roughly 50 KB -- negligible for any production workload.

10. Migration Guide

Switching between SDKs is straightforward because all three share the same event schema, API key format, and agent registration model. Events from any SDK appear identically in the Trusera dashboard.

10.1 Python to TypeScript

Python	TypeScript Equivalent
`TruseraClient(api_key=...)`	`new TruseraClient({ apiKey: ... })`
`client.register_agent(name, framework)`	`await client.registerAgent(name, framework)`
`client.track(Event(...))`	`client.track(createEvent(...))`
`client.flush()`	`await client.flush()`
`client.close()`	`await client.close()`
`@monitor(event_type=...)`	`interceptor.install(client, ...)`
`EventType.TOOL_CALL`	`EventType.TOOL_CALL`
`TruseraCallbackHandler`	`TruseraLangChainHandler`

Key differences:

TypeScript flush() and close() return Promises; always await them.
The TypeScript SDK intercepts fetch, axios, and undici automatically. Wrap tool functions manually with createEvent() if you need per-function tracking.
CrewAI and AutoGen integrations are Python-only.

10.2 Python to Go

Python	Go Equivalent
`TruseraClient(api_key=...)`	`trusera.NewClient("api-key", ...)`
`client.register_agent(name, fw)`	`client.RegisterAgent(name, fw)`
`client.track(Event(...))`	`client.Track(trusera.NewEvent(...))`
`client.flush()`	`client.Flush()`
`client.close()`	`client.Close()`
`@monitor(...)`	`trusera.WrapHTTPClient(...)`
`EventType.TOOL_CALL`	`trusera.EventToolCall`
`with TruseraClient(...) as c:`	`defer client.Close()`

Key differences:

Go uses functional options (WithBaseURL, WithBatchSize) instead of keyword arguments.
Go has BlockPatterns for URL-based policy enforcement; Python relies on Cedar policies.
No framework-specific callback handlers in Go. Use WrapHTTPClient for HTTP interception and Track() for manual event recording.
Go events use a builder pattern: NewEvent(...).WithPayload(k, v).

10.3 TypeScript to Go

TypeScript	Go Equivalent
`new TruseraClient({ apiKey })`	`trusera.NewClient(apiKey)`
`client.registerAgent(name, fw)`	`client.RegisterAgent(name, fw)`
`client.track(createEvent(...))`	`client.Track(trusera.NewEvent(...))`
`await client.flush()`	`client.Flush()`
`await client.close()`	`client.Close()`
`interceptor.install(client, opts)`	`trusera.WrapHTTPClient(httpClient, client, opts)`
`interceptor.uninstall()`	(use a different `http.Client` or stop using the wrapper)
`EventType.TOOL_CALL`	`trusera.EventToolCall`

Key differences:

Go wraps http.Client explicitly; TypeScript monkey-patches globalThis.fetch.
Go's WrapHTTPClient returns a new *http.Client; the original is untouched.
TypeScript's excludePatterns uses regex strings; Go's ExcludePatterns uses simple substring matching.
Go does not support policyUrl in interceptor options; use BlockPatterns instead.

10.4 Shared Agent Identity

The same agent ID works across all SDKs. If you register an agent in Python and later switch to Go, use the same agent ID to maintain continuity:

# Python: register agent
client.register_agent("my-agent", "custom")

// Go: reuse the same identity
client := trusera.NewClient("tsk_same_api_key",
    trusera.WithAgentID("my-agent"),
)

All historical events remain associated with my-agent in the Trusera dashboard, regardless of which SDK generated them.