Add ai_agent object and extend ai_operation profile coverage

[Aniak5]

First step toward agentic AI observability per #1640. This PR introduces the ai_agent object and threads it through the schema so that data-plane events across multiple categories can attribute activity to the agent that initiated it. Delegation, lineage, and the AI control-plane event classes are intentionally deferred to follow-up PRs.

Changes

New object

• objects/ai_agent.json — autonomous AI agent identity with:
• uid (required) — stable logical agent identifier assigned by the agent's authoritative source (control plane, registry, or issuing IdP); persists across restarts and instances
• instance_uid — restart-sensitive identifier for a specific running instance
• name — human-readable agent name
• type / type_id — agent framework with enum: Native, LangChain, AutoGen, CrewAI, Other (communication protocols like MCP/A2A are per-event rather than per-agent and are not modeled
  here)
• ai_model — the model backing the agent at the time of action
• version — agent version (its own code or configuration revision, distinct from the model version on ai_model.version), for correlating behavioral changes with charter or configuration revisions
• charter — file-typed reference to the document that defines the agent's durable role, responsibilities, constraints, and operating boundaries (e.g., system prompt or constitution); supports hashes for content integrity and signatures for provenance
• Distinct from the existing agent object (which models security sensors such as EDR, DLP, APM).

Dictionary

• dictionary.json — added top-level ai_agent attribute referencing the new ai_agent object type.
• dictionary.json — added top-level charter attribute (file type) for documents defining the role, scope, and operating bounds of an entity.

Profile

• profiles/ai_operation.json — added optional ai_agent attribute (context group) so any event class adopting the profile can carry agent attribution.

Object updates

• objects/actor.json — added optional ai_agent attribute and included it in the at_least_one constraint, so an actor can be identified as an autonomous AI agent rather than (or in addition to) a user, IAM role, process, etc.

• objects/process.json — added optional ai_agent attribute, allowing a process to be identified as the runtime of a specific AI agent.

  Event classes — added ai_operation profile

  • events/system/system.json (base class) — propagates the profile to all System Activity events
  • events/network/network.json (base class) — propagates the profile to all Network Activity events
  • events/application/web_resources_activity.json — does not extend the network base, added directly
  • events/network/email_activity.json — does not extend the network base, added directly

These join process_activity, datastore_activity, and api_activity, which already had the profile.

Closes part of #1640.

[github-actions]

Schema Description Review

Automated suggestions for improving description clarity for LLM consumption. These are advisory — not required changes.

Looking at this OCSF schema PR, I'll check against my previous review and assess the current state.

Progress Check from Previous Review

✅ Fixed: CHANGELOG formatting issue resolved

• The CHANGELOG now includes the required PR reference [#1641](https://github.com/ocsf/ocsf-schema/pull/1641) (previous issue resolved)

Current Review Findings

Suggestions

1. Object: web_resources_activity
   Attribute: web_resources_result
   Issue: Missing attribute in compiled schema despite being listed in _changed_attributes
   Current: (attribute not found in compiled output)
   Suggested: This appears to be a compilation issue - the attribute is marked as changed but not present in the compiled schema. Please verify the attribute definition exists in the source files.

Summary

The AI agent integration in this PR is well-designed with clear, self-contained descriptions that effectively distinguish between AI agents (autonomous task performers) and the existing agent object (security sensors). All visible attribute descriptions provide good semantic clarity for LLM consumption. However, there appears to be a compilation issue where web_resources_result is marked as changed but missing from the compiled output. The previously identified CHANGELOG formatting issue has been resolved.

[mikeradka]

This is a strong foundation. What would really help reviewers and early implementers is a few concrete end-to-end examples - what an event looks like on the wire from both the producer and consumer sides.

A couple of things I'm curious about:

Producer side - how should an event source populate this in practice? For example, when a LangChain agent reads a file via a tool call, does ai_agent appear on actor, process, or both? How does a producer distinguish between the agent's identity and the underlying process that made the action?

Consumer side - what's the intended correlation pattern? How would an analyst pivot from "this file was deleted" to "which agent instance was responsible and what model was it running?" across the uid/instance_uid split?

A pair of abbreviated JSON event snippets would go a long way toward building confidence that the attribute
placement choices are unambiguous for implementers - and make it easier to move forward knowing those decisions
are solid

[Levaj2000]

+1 to the ask for wire examples, @mikeradka. Rather than a hypothetical, here's a real (scrubbed) row from our gateway — we log every agent request as an immutable, hash-chained record, so I can speak to what a producer can and can't actually populate, which is where the placement questions get real.

This is our own ada agent calling its read_file tool through the gateway — allowed under policy v36 — as an API Activity (class_uid 6003) with the ai_operation profile (UUIDs/hashes scrubbed):

{
  "activity_id": 2,
  "category_uid": 6,
  "class_uid": 6003,
  "type_uid": 600302,
  "severity_id": 1,
  "time": 1777912519552,
  "metadata": {
    "version": "1.9.0-dev",
    "profiles": ["ai_operation"],
    "correlation_uid": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
  },
  "action": "Allowed",
  "action_id": 1,
  "api": { "operation": "read_file", "service": { "name": "ada-tools" } },
  "http_request": { "http_method": "POST", "url": { "path": "/ada/tools/read_file" } },
  "actor": {
    "user": { "uid": "11111111-2222-4333-8444-555566667777", "type_id": 1 }
  },
  "ai_agent": {
    "uid": "a9c3e7d1-2b4f-4e6a-9c8d-3f5a7b1e2c4d",
    "name": "ada"
  },
  "unmapped": {
    "policy_version": 36,
    "status_code": 200,
    "latency_ms": 90,
    "upstream_latency_ms": 45
  }
}

The honest producer answer to your uid / instance_uid question: as a gateway (a proxy in front of the tool/model APIs), I can populate ai_agent.uid — it's derived from the agent's credential — but I cannot populate ai_agent.instance_uid. I observe the agent's identity, not its process lifecycle; instance_uid is only knowable to the agent runtime self-reporting. Same with actor.process: a proxy sees no OS process, so it's legitimately empty — note this is a file read and yet there's no filesystem object in sight, because the gateway captures it as the API/tool call it actually saw, not an OS file op. So the two layers you asked about (agent identity vs. underlying process) aren't just separable — for a whole class of producers they arrive on different events from different vantage points, and the schema is right to keep them independent. Suggest the spec note that instance_uid is "populate when self-reported; gateways/proxies legitimately omit."

Consumer pivot (your correlation question): ai_agent.uid → everything that logical agent did; metadata.correlation_uid → the full request chain across services. We use correlation_uid exactly as CoSAI's Agentic IAM framework prescribes (Appendix E, "prove control on demand"). On "what model was it running?" — for a tool call the gateway log doesn't carry model identity; that lives on the model-inference events, correlated by the same correlation_uid. (Worth noting ai_model isn't always knowable to the producer of a given event.)

Two placement questions back at you: (1) policy decisions map cleanly here — action_id: 1 (Allowed) / 2 (Denied) is exactly right for allow/deny. But our gateway carries a third decision state, error (policy-eval or upstream failure), and there's no action_id enum for it, so it falls to 99 (Other). Is Other the intended home for an errored decision, or is that better modeled on status_id? And (2) we carry a policy_version per decision (CoSAI's logging schema asks for it too) — is there a home for that, or is unmapped/enrichment the expectation for now?

Thank you for the review - Jeff

[Aniak5]

Thanks for the review @mikeradka — agreed, the placement question deserves a concrete answer before this lands. Here's how we're thinking about it.

The placement landscape

We currently have ai_agent available in three places: on the ai_operation profile, on actor, and on process. The instinct is that this is redundant — but each placement composes differently when you walk into nested objects (actor.process, process.parent_process, evidences.actor, etc.). The question isn't really "which one of the three?" — it's "what's the canonical home, and where do nested instances earn their keep?"

Why ai_operation should carry ai_agent directly

One option we considered was removing ai_agent from the ai_operation profile entirely and relying on actor.ai_agent (reached via the host profile, which is applied to most event classes). We don't think that's the right path:

• Producer discovery is indirect. A producer logging an AI-relevant event reaches for the ai_operation profile first — that's the natural mental model. Telling them "actually, populate actor.ai_agent from the host profile, even though you've already applied ai_operation" creates exactly the kind of cross-profile indirection that breeds inconsistent mappings.
• Profiles should be self-contained kits. Applying ai_operation and finding agent identity inside it is the obvious contract. If agent identity has to come from a different profile, the uai_operation profile feels incomplete — and producers will guess wrong.
• Not every AI-relevant event has an actor. The host profile gives actor to most classes, but not all (discovery/query events, application events, future model_inference_activity-style
  classes). Pinning agent identity to actor would leave those gaps uncovered, while a profile-level placement covers them uniformly.

So ai_operation.ai_agent is the canonical home. The question is whether actor.ai_agent and process.ai_agent still earn their place alongside it.

Placement table

Placement	Pros	Cons
ai_operation.ai_agent (profile-level)	Producer's natural discovery path. Self-contained: producers don't need to combine multiple profiles to log an agent reference. Works on event classes that don't have actor (discovery, application, future model-inference events).	None significant. This is the canonical home.
actor.ai_agent	Composes via evidences.actor.ai_agent in findings — a detection about agent-driven activity can carry the agent identity inside the evidence trail. Aligns with the actor model (agent as a non-human principal) for events where actor is the natural aggregator.	On the top-level event itself, largely redundant with the profile-level reference. If we don't expect producers to use it for delegated-authority cases (actor.user + actor.ai_agent), it adds a placement choice without semantic value.
process.ai_agent	Composes via process.parent_process.ai_agent to express agent-to-agent delegation at the runtime layer — when an orchestrator agent spawns a worker agent, the worker carries ai_operation.ai_agent and the orchestrator surfaces only through parent_process.ai_agent; nothing else on the event preserves that spawning relationship between agents. Also composes via actor.process.ai_agent for "the running process is the agent's runtime" (endpoint forensics, container attribution).	Redundant at the top level (the profile-level ai_agent already carries the acting agent's identity), and the composition cases are real but apply mainly in multi-agent / endpoint-forensics scenarios — single-agent events get nothing extra from it.

Worth considering: adding to evidences

We could also add ai_agent to the evidences object directly, alongside actor and process. That would let findings carry agent identity at the top of the evidence trail without requiring it to be reached via evidences.actor.ai_agent. This may be the cleaner path for detection-finding consumers.

Producer-side convention (proposed)

Canonical placement: ai_operation.ai_agent is the primary home for agent identity on any event applying the ai_operation profile. Populate this whenever an AI agent is involved.

Nested placements (actor.ai_agent, process.ai_agent, process.parent_process.ai_agent) are populated only when the binding carries information beyond the canonical reference — e.g., a child process whose parent is an agent runtime, or finding evidence that links agent activity to a detection.

Examples

LangChain agent reads a file via a tool call:

{
  "class_uid": 1001,
  "activity_id": 2,
  "ai_agent": {
    "uid": "agent-research-assistant",
    "instance_uid": "i-7c2f9a",
    "name": "Research Assistant",
    "type_id": 4,
    "type": "LangChain",
    "version": "1.4.2",
    "ai_model": {
      "uid": "claude-sonnet-4-6",
      "name": "Claude Sonnet 4.6",
      "version": "20260514",
      "vendor_name": "Anthropic"
    },
    "charter": {
      "name": "research_assistant_charter.md",
      "hashes": [
        { "algorithm_id": 3, "value": "8f3b2c1d4e7a..." }
      ]
    }
  },
  "file": {
    "name": "q4_earnings.pdf",
    "path": "/data/reports/q4_earnings.pdf"
  }
}

Agent spawns a subprocess that performs the activity (parent_process binding):

  {
    "class_uid": 1007,
    "activity_id": 1,
    "ai_agent": {
      "uid": "agent-deploy-worker",
      "instance_uid": "i-9e22",
      "name": "Deploy Worker",
      "type_id": 1,
      "type": "Native",
      "ai_model": { "uid": "claude-haiku-4-5" }
    },
    "process": {
      "pid": 51220,
      "name": "python3.13",
      "parent_process": {
        "pid": 48211,
        "name": "python3.13",
        "ai_agent": {
          "uid": "agent-devops-orchestrator",
          "instance_uid": "i-44c1",
          "name": "DevOps Orchestrator",
          "type_id": 3,
          "type": "A2A",
          "ai_model": { "uid": "claude-opus-4-7" }
        }
      }
    }
  }

The acting agent is agent-deploy-worker — that's the agent on ai_operation.ai_agent and the agent running in the current process. Its parent process is another agent (agent-devops-orchestrator, an A2A orchestrator) that delegated this work. process.parent_process.ai_agent is the only place this delegating-agent identity surfaces on the event — without it, you'd lose the spawning relationship between agents.

Questions for the group

1. Is the canonical-placement-with-nested-bindings convention the right model, or should we simplify to profile-level only and accept the loss of parent_process / evidence composition?
2. Should we add ai_agent directly to the evidences object?

@davemcatcisco @jedwardsol if you get a chance, I'd really appreciate your feedback on adding ai_agent to actor and process. That's probably where endpoint telemetry has the biggest impact.

[davemcatcisco]

As well as the comments I've made about the AI profile being available in all System Activity and Network events, it also needs to be available in all events in the Identity & Access Management category by adding it to the iam base event for that category.

[davemcatcisco]

@Aniak5 - As we discussed in the Network/AI call just now, I think there is a strong argument for the ai_operation profile also being applicable in the Identity & Access Management event category. All events in that category extend the iam base event, so the profile would only need to be added there.

[davemcatcisco]

Looks good to me now. Thanks, @Aniak5.

[davemcatcisco]

@mikeradka will need to re-approve.

[Levaj2000]

LGTM — solid attribution foundation for ai_agent, and the charter naming resolved cleanly. Thanks @Aniak5!