Why the schema exists
AI agent activity is emitted from many places: local developer machines, CI jobs, cloud-hosted coding agents, SDK integrations, OpenTelemetry exporters, and runtime-specific hook systems. Each source has its own event names, payload shapes, identifiers, and ideas about what counts as a prompt, tool call, command, approval, file change, or policy decision. Beacon’s unified telemetry schema turns those different signals into one normalized event model. The goal is to make agent activity searchable, detectable, and explainable across local, CI, and cloud environments without requiring every downstream rule, dashboard, or SIEM parser to understand each runtime’s native format.What normalization provides
The schema gives every event a consistent backbone:| Schema concept | Purpose |
|---|---|
event | Describes what happened with normalized actions such as prompt.submitted, tool.invoked, command.executed, file.modified, approval.requested, or mcp.tool_invoked |
harness | Identifies the agent runtime or integration that produced the signal |
origin | Distinguishes local, CI, and cloud telemetry while preserving a shared event shape |
run and session | Connects activity to CI runs, cloud-agent jobs, local sessions, repositories, branches, and working directories |
tool, command, file, mcp, approval, and policy | Captures the entities analysts and detections need to understand agent behavior |
content | Records whether prompt or tool content was included, redacted, truncated, or omitted |
Required fields
| Field | Meaning |
|---|---|
timestamp | UTC event time |
vendor | Always beacon |
product | Current product identifier, endpoint-agent |
schema_version | Current public schema version, 1.0 |
event.kind | Event family, currently agent_runtime |
event.action | Normalized action such as command.executed or tool.invoked |
event.category | Event category, provided by the runtime or inferred from event.action when possible |
severity | info, low, medium, high, or critical |
endpoint | Host and operating system context |
harness | Runtime that produced the signal |
How it extends OpenTelemetry
Beacon accepts OpenTelemetry attributes, including the GenAI semantic conventions, and projects them into fields that are easier to query across agent runtimes. OpenTelemetry context is preserved undergen_ai where available, while commonly investigated values are also normalized into Beacon fields such as model, tool.name, prompt.text, command.command, file.path, and gen_ai.usage.
This lets teams use OpenTelemetry-native data without giving up a security-focused vocabulary for agent behavior. A detection can ask for a normalized command, MCP tool, approval decision, or file operation instead of branching on every source runtime’s attribute names.
Why it matters
The normalized schema is the contract between collection, detection, investigation, and forwarding. It lets Asymptote:- Correlate agent activity across local endpoints, ephemeral CI jobs, and cloud agent sessions.
- Write detections once against stable fields instead of per-runtime payloads.
- Preserve source-specific OpenTelemetry and GenAI context without forcing downstream tools to parse raw traces.
- Keep prompt, tool, command, file, approval, policy, and token-usage telemetry comparable across supported harnesses.
- Forward one predictable JSONL shape into customer-managed analytics, SIEM, object-storage, and review workflows.
Read next
Schema normalization
See how OTLP attributes and hook payloads map into Beacon fields and actions.
Schema fields
Review entities, optional context, and shared top-level fields.
Schema examples
Inspect example events and content handling behavior.
Data inventory
Review runtime coverage and the event fields Beacon can write when a source provides them.
Related
Core Concepts
Review the glossary behind events and entities.
Open Source Architecture
See how runtime telemetry becomes normalized JSONL.
Detections
See how events are evaluated by threat rules.
Wazuh
Configure Wazuh ingestion for Beacon events.
Datadog
Configure Datadog Agent custom log collection for Beacon events.
Sumo Logic
Configure Sumo Logic HTTP Source forwarding for Beacon events.