Sessions API

Overview

Evaluation sessions group related evaluations into a single logical workflow. This is especially useful for multi-step processes like agent conversations, document review pipelines, or multi-turn chat interactions where policies need to consider the full context of what has happened so far.

As evaluations run within a session, Aguardic automatically tracks actions, data tags, tools used, and action counts. This accumulated context is available to the policy engine, enabling rules like "block if more than 5 tools have been called" or "warn if PII has been detected in this session."

Session Lifecycle

Sessions follow a simple lifecycle: ACTIVE to COMPLETED, TERMINATED, or EXPIRED.

• ACTIVE -- The session is open and accepting evaluations.
• COMPLETED -- The session ended normally.
• EXPIRED -- The session's expiresAt timestamp has passed.
• TERMINATED -- The session was ended early (e.g., due to a violation or manual stop).

Authentication

All session endpoints require a per-integration API key in the Authorization header. See Authentication for details.

Create Session

Create a new evaluation session to group subsequent evaluations.

POST /v1/evaluation-sessions

Request Body

Example

curl -X POST https://api.aguardic.com/v1/evaluation-sessions \
  -H "Authorization: Bearer ag_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "externalSessionId": "conv-2024-01-15-abc",
    "expiresAt": "2024-01-15T11:30:00.000Z",
    "metadata": {
      "userId": "user-123",
      "channel": "web-chat"
    }
  }'

Response

{
  "success": true,
  "statusCode": 201,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "ACTIVE",
    "entityId": null,
    "externalSessionId": "conv-2024-01-15-abc",
    "startedAt": "2024-01-15T10:30:00.000Z",
    "expiresAt": "2024-01-15T11:30:00.000Z",
    "metadata": {
      "userId": "user-123",
      "channel": "web-chat"
    }
  }
}

Use the returned id as the sessionId parameter in subsequent Evaluate requests.

End Session

End an active session. Once ended, no further evaluations can be added.

POST /v1/evaluation-sessions/:sessionId/end

Request Body

Example

curl -X POST https://api.aguardic.com/v1/evaluation-sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/end \
  -H "Authorization: Bearer ag_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"status": "COMPLETED"}'

Response

{
  "success": true,
  "statusCode": 200,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "COMPLETED",
    "endedAt": "2024-01-15T10:45:00.000Z",
    "actionCount": 5,
    "dataTags": ["pii", "financial"],
    "toolsUsed": ["send_email", "query_database"]
  }
}

Session Context in Policy Evaluation

When you include a sessionId in an Evaluate request, the policy engine receives the session's accumulated context:

• dataTags -- All data categories detected across previous actions in the session.
• toolsUsed -- All tools or operations invoked so far.
• actionCount -- How many evaluations have run in this session.
• recentActions -- The most recent actions for pattern detection.

This enables policies that reason about the full workflow, not just individual requests. For example:

• Block if the session has already triggered 3 warnings
• Require approval if PII was detected earlier in the session and the agent now wants to send an email
• Escalate severity when actionCount exceeds a threshold

Next Steps

• Evaluate API -- Send content for policy evaluation
• Evaluation Sessions Guide -- Patterns and best practices for sessions
• AI Systems -- Register AI systems and link integrations