Agent Scenario Management API

These endpoints power the admin scenario console under /admin/ai-agent/scenarios. They allow super admins to create automated agent scenarios that drive the external simulation platform.

File Attachment Workflow

Scenarios can now include file attachments alongside inline text and URLs. File attachments are stored in the existing uploaded_files table and referenced from the scenario payload.

1. Upload a File

Use the files upload endpoint to store the document before creating the scenario:

POST /api/v1/files/upload?processContent=true&category=agent-scenario
Content-Type: multipart/form-data

file=<binary>

A successful response returns the stored file metadata:

{
  "success": true,
  "file": {
    "id": "upl_123",
    "fileName": "guardrails.pdf",
    "fileSize": 248512,
    "mimeType": "application/pdf",
    "uploadedAt": "2025-10-06T16:42:18.201Z",
    "processingStatus": "COMPLETED"
  },
  "processing": {
    "textLength": 1432,
    "hasContent": true
  }
}

Keep the id – it is referenced by the scenario payload.

2. Create a Scenario With the File Attachment

File attachments live in the attachments array beside the existing text/url items:

POST /api/admin/ai-agent/scenarios
Content-Type: application/json

{
  "name": "Compliance Snapshot",
  "type": "PROJECT_GATEWAY",
  "projectGatewayId": "gateway_proprietary_guardrail",
  "runtimePrompt": {
    "prompt": "Summarise the latest guardrail report",
    "systemPrompt": "Return JSON with {\"status\",\"notes\"}",
    "temperature": 0.2,
    "maxTokens": 600
  },
  "attachments": [
    { "type": "text", "content": "Highlight any warnings above medium." },
    { "type": "file", "fileId": "upl_123", "fileName": "guardrails.pdf", "mimeType": "application/pdf", "fileSize": 248512 }
  ],
  "warningThresholds": [
    { "warningType": "SUPABASE_RATE_LIMIT", "threshold": 1, "unit": "COUNT" }
  ]
}

During execution the agent runner fetches the uploaded file, injects the extracted text (or a placeholder if no text is available) into the gateway request, and records file metadata on the run for auditing.

Payload Reference

Attachment objects accept the following shapes:

Type	Required fields	Optional fields
text	content	–
url	url	–
file	fileId	fileName, mimeType, fileSize

Note: fileId must reference a record owned by the same company. Uploads performed via the admin UI automatically enforce this guard.

Responses

Scenario payloads returned by the API now include file attachment metadata so the admin UI can display the file name, MIME type, and size alongside existing text/URL entries.

GET /api/admin/ai-agent/scenarios
{
  "scenarios": [
    {
      "scenarioId": "scenario_project_gateway_proprietary",
      "attachments": [
        { "type": "file", "fileId": "upl_123", "fileName": "guardrails.pdf", "mimeType": "application/pdf", "fileSize": 248512 }
      ]
    }
  ]
}

Resources

• Upload endpoint: POST /api/v1/files/upload
• Scenario collection: GET|POST /api/admin/ai-agent/scenarios
• Scenario detail: PATCH /api/admin/ai-agent/scenarios/{scenarioId}
• Run trigger: POST /api/admin/ai-agent/run

Attachments are optional; scenarios without attachments continue to operate the same way.