Agent Session Auditing Admin Guide

Arbitex agent session auditing tracks multi-turn AI agent interactions across MCP servers and tool calls. When an AI agent conducts a multi-step workflow — querying a database, calling an API, writing to a file system — every tool call in that session is linked by a session ID, evaluated against per-agent authorization policies, scored for risk, and logged to the immutable audit chain.

Agent session auditing extends MCP Governance. MCP governance handles per-server policy enforcement and DLP scanning of individual tool calls. Agent session auditing adds the session layer: linking tool calls into multi-turn chains, enforcing per-agent-identity tool authorization, computing behavioral risk scores, and providing a timeline view for investigation.

What agent session auditing provides:

• Session linking — all tool calls within an agent session share a session_id, enabling chain analysis across servers
• Per-agent tool authorization — different agents can have different tool permissions, independent of the server-level policies
• Risk scoring — behavioral signals (breadth, violation rate, speed anomaly, novelty) produce a composite risk score per session
• Session timeline — ordered view of every tool call with policy decisions, latency, and payloads for forensic review
• Chain-of-thought capture — when the model exposes reasoning tokens, they are stored in audit metadata

Note

Agent session auditing requires MCP governance to be configured. Register MCP servers and bind policies before creating agent identities and tool authorization policies.

---

Agent sessions

An agent session represents a single multi-turn interaction where an AI agent makes one or more tool calls to accomplish a task. Sessions have a defined lifecycle: they are explicitly started, accumulate tool call events, and are ended when the agent completes its work or the session times out.

Session lifecycle

1. Start — The orchestration framework calls POST /api/agent/sessions/ with the agent identity and optional metadata. The platform returns a session_id.

2. Tool calls — Each MCP tool call includes the session_id in its headers. The platform links the tool call audit event to the session, evaluates per-agent authorization policies, runs DLP scanning, and records the policy decision.

3. End — The orchestration framework calls PATCH /api/agent/sessions/:id with status: "ended". The platform finalizes the session, computes the aggregate risk score, and emits a session.ended audit event.

If no tool calls are recorded for 30 minutes (configurable), the platform automatically ends the session with status: "timed_out".

Session ID propagation

The session_id is a UUIDv7 that propagates through all audit events generated during the session. This enables:

• Chain analysis — query all tool calls in a session to reconstruct the agent’s decision path
• Cross-server correlation — when an agent calls tools on multiple MCP servers in one session, all calls share the same session ID
• Compliance reporting — export session-scoped audit trails for regulatory review

Pass the session ID in the X-Agent-Session-Id header on MCP tool call requests:

X-Agent-Session-Id: 019577a3-7c4e-7def-8a1b-3c5d7e9f1a2b

Chain-of-thought capture

When the AI model exposes reasoning tokens (chain-of-thought), the platform captures them in the session audit metadata. This provides visibility into why the agent chose specific tool calls, which is valuable for:

• Post-incident investigation — understanding agent decision-making during a security event
• Compliance audits — demonstrating that agent actions followed policy intent
• Behavioral analysis — identifying patterns that precede policy violations

Chain-of-thought data is stored encrypted at rest and is accessible only to admin users with the audit:read permission.

---

Agent tool authorization

Agent tool authorization controls which tools each agent identity can invoke, independent of server-level policies. While MCP governance defines what tools a server exposes and what DLP rules apply, agent tool authorization defines what each agent is permitted to call.

How authorization works

Each agent identity has a tool authorization policy that specifies allowed and denied tools. When a tool call arrives with a session ID, the platform:

1. Identifies the agent from the session
2. Checks the agent’s tool authorization policy
3. If the tool is explicitly denied, blocks the call (logged as decision: "block")
4. If the tool is explicitly allowed, proceeds to MCP governance evaluation (DLP, policy rules)
5. If the tool is not listed, applies the default behavior (allow or deny, configurable per policy)

Caution

Agent tool authorization runs before MCP governance policy evaluation. A tool call blocked by agent authorization never reaches the DLP pipeline. A tool call allowed by agent authorization can still be blocked by MCP governance policies.

Default behavior

Each tool authorization policy has a default_action field:

Value	Behavior
allow	Tools not listed in the policy are allowed. Use when the agent needs broad access and you want to deny specific tools.
deny	Tools not listed in the policy are denied. Use for restricted agents that should only access explicitly approved tools.

New agent identities default to default_action: "allow" to avoid breaking existing integrations. For high-risk agents, set default_action: "deny" and explicitly allow only the required tools.

Wildcard patterns

Tool names in authorization policies support wildcard patterns:

Pattern	Matches
salesforce:*	All tools on the salesforce server
*:read_*	Any tool starting with read_ on any server
jira:create_issue	Exactly the create_issue tool on jira

Pattern format is server_name:tool_name. If the server name is omitted, the pattern matches across all servers.

Managing agent identities

Agent identities are created and managed via the admin API. Each identity represents a specific agent (or agent class) in your orchestration framework.

Create identity

curl -X POST https://your-platform/api/agent/policies/ \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "research-assistant",
    "description": "Read-only research agent for knowledge base queries",
    "default_action": "deny",
    "allowed_tools": [
      "knowledge-base:search",
      "knowledge-base:get_document",
      "salesforce:get_account"
    ],
    "denied_tools": []
  }'

Update policy

curl -X PUT https://your-platform/api/agent/policies/{policy_id} \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_tools": [
      "knowledge-base:search",
      "knowledge-base:get_document",
      "salesforce:get_account",
      "salesforce:get_contact"
    ],
    "denied_tools": [
      "salesforce:delete_*"
    ]
  }'

List policies

curl https://your-platform/api/agent/policies/ \
  -H "Authorization: Bearer $ADMIN_TOKEN"

---

Risk scoring

Agent session risk scoring evaluates behavioral signals across the session to identify potentially compromised or misbehaving agents. The risk score is a composite value from 0 to 100, computed from four independent signals.

Risk signals

Signal	Weight	What it measures
Breadth	25%	Number of distinct MCP servers accessed in the session. Agents that suddenly reach across many servers may be compromised.
Violation rate	35%	Ratio of blocked or redacted tool calls to total calls. A high violation rate indicates the agent is repeatedly hitting policy boundaries.
Speed anomaly	20%	Tool call frequency compared to the agent’s historical baseline. Unusually rapid calls may indicate automated exploitation.
Novelty	20%	Tool calls to servers or tools the agent has never used before. First-time access to sensitive servers raises the score.

Score calculation

Each signal produces a sub-score from 0 to 100. The composite score is the weighted sum:

risk_score = (breadth × 0.25) + (violation_rate × 0.35) + (speed_anomaly × 0.20) + (novelty × 0.20)

The composite score is computed incrementally as tool calls arrive during the session and finalized when the session ends.

Thresholds and alerting

Risk score bands trigger alerts when a session exceeds a defined level:

Threshold	Default	Action
low	25	Informational. Logged but no alert.
medium	50	Alert sent to configured destinations (webhook, email).
high	75	Alert sent. Session flagged for admin review.
critical	90	Alert sent. Session can be auto-suspended (if enabled).

Roadmap — thresholds not yet org-configurable

The agent session risk alert threshold is currently hardcoded at 75.0 in the platform codebase (CVP Track 14 audit finding #28). The agent_risk_thresholds.* config keys documented below are planned for a future release but are not yet wired into the risk scoring path. Per-org threshold tuning will land with the Epic AG follow-on; until then all orgs share the default bands shown above.

If you need custom alert fan-out today, subscribe a webhook to the agent.risk_alert event and apply downstream filtering in your SIEM.

Alert destinations use the existing webhook infrastructure. Configure a webhook with event type agent.risk_alert to receive risk notifications.

---

Session timeline

The session timeline provides an ordered view of every tool call in a session, including policy decisions, latency, payloads, and risk score progression. Use the timeline for:

• Incident investigation — trace exactly what an agent did, in order, with full context
• Compliance review — demonstrate that every tool call was evaluated against policy
• Performance analysis — identify slow tool calls or bottleneck servers

Reading the timeline

Each entry in the timeline contains:

Field	Description
sequence	Monotonically increasing call number within the session
timestamp	ISO 8601 timestamp of the tool call
server_name	MCP server that received the call
tool_name	Tool that was invoked
direction	request (outbound to server) or response (inbound from server)
decision	Policy decision: allow, block, redact, or log
matched_rules	Policy rules that matched this call (array of rule IDs and names)
latency_ms	Round-trip time for the tool call in milliseconds
risk_score	Cumulative session risk score at this point in the timeline
payload_preview	Truncated payload (first 500 chars). Full payload available via detail endpoint.
dlp_findings	DLP detections on this call (detector name, severity, action taken)

Example timeline

{
  "session_id": "019577a3-7c4e-7def-8a1b-3c5d7e9f1a2b",
  "agent_name": "research-assistant",
  "status": "ended",
  "risk_score": 32,
  "tool_call_count": 4,
  "timeline": [
    {
      "sequence": 1,
      "timestamp": "2026-04-01T10:00:01Z",
      "server_name": "knowledge-base",
      "tool_name": "search",
      "direction": "request",
      "decision": "allow",
      "matched_rules": [],
      "latency_ms": 45,
      "risk_score": 5,
      "payload_preview": "{\"query\": \"Q3 revenue projections\"}",
      "dlp_findings": []
    },
    {
      "sequence": 2,
      "timestamp": "2026-04-01T10:00:03Z",
      "server_name": "knowledge-base",
      "tool_name": "get_document",
      "direction": "request",
      "decision": "allow",
      "matched_rules": [],
      "latency_ms": 120,
      "risk_score": 8,
      "payload_preview": "{\"doc_id\": \"fin-2026-q3-draft\"}",
      "dlp_findings": []
    },
    {
      "sequence": 3,
      "timestamp": "2026-04-01T10:00:05Z",
      "server_name": "salesforce",
      "tool_name": "get_account",
      "direction": "request",
      "decision": "allow",
      "matched_rules": ["rule-pii-scan"],
      "latency_ms": 230,
      "risk_score": 22,
      "payload_preview": "{\"account_id\": \"001XX000003GHP\"}",
      "dlp_findings": [
        {
          "detector": "pii-email",
          "severity": "medium",
          "action": "redact"
        }
      ]
    },
    {
      "sequence": 4,
      "timestamp": "2026-04-01T10:00:08Z",
      "server_name": "salesforce",
      "tool_name": "update_account",
      "direction": "request",
      "decision": "block",
      "matched_rules": ["agent-auth-deny"],
      "latency_ms": 2,
      "risk_score": 32,
      "payload_preview": "{\"account_id\": \"001XX000003GHP\", \"field\": \"notes\"}",
      "dlp_findings": []
    }
  ]
}

In this example, the research assistant was authorized for read operations but attempted a write (update_account), which was blocked by agent tool authorization. The risk score increased due to the violation (signal: violation rate) and cross-server access (signal: breadth).

---

Configuration

Risk threshold configuration

Roadmap — config keys not yet active

The config keys in the table below describe the planned org-level tuning surface. Today the platform uses a single hardcoded alert threshold of 75.0 regardless of org (CVP Track 14 audit finding #28). Writing to agent_risk_thresholds.* via the admin config API has no effect on runtime behaviour. Per-org configuration will be wired up in a follow-up release.

Planned org-level config keys:

Config key	Type	Default	Description
agent_risk_thresholds.low	integer	25	Below this: no alert
agent_risk_thresholds.medium	integer	50	Alert sent to webhook destinations
agent_risk_thresholds.high	integer	75	Alert + session flagged for review
agent_risk_thresholds.critical	integer	90	Alert + optional auto-suspend
agent_risk_thresholds.auto_suspend_on_critical	boolean	true	Automatically suspend sessions that reach critical threshold

Session timeout

Config key	Type	Default	Description
agent_session_timeout_minutes	integer	30	Minutes of inactivity before a session is auto-ended with status: "timed_out"

Alert destinations

Agent risk alerts use the platform’s webhook system. Create a webhook subscription for agent events:

curl -X POST https://your-platform/api/v1/admin/webhooks \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://siem.example.com/arbitex-agent-alerts",
    "events": ["agent.risk_alert", "agent.session_ended"],
    "secret": "webhook-signing-secret"
  }'

Agent identity management

Agent identities map to agent names in your orchestration framework. Best practices:

• One identity per agent role — create separate identities for research-assistant, code-reviewer, data-analyst rather than one shared identity
• Least privilege — use default_action: "deny" and explicitly allow required tools
• Review periodically — list all agent policies and remove identities for decommissioned agents
• Audit first — before tightening policies, review session timelines to understand current tool usage patterns

For the API reference covering all session and policy endpoints, see Agent Session API Reference.