AgentToolGamebookSubmissionRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/contraforce/json-schema/contraforce-agent-tool-gamebook-submission-request-schema.json",
  "title": "AgentToolGamebookSubmissionRequest",
  "description": "Request DTO for the agent's submit-gamebook tool. Allows the agent to queue one or more\nremediation gamebooks against an incident as it investigates.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/contraforce-agent-tools-api-openapi.yml#/components/schemas/AgentToolGamebookSubmissionRequest",
  "type": "object",
  "properties": {
    "incident_number": {
      "pattern": "^-?(?:0|[1-9]\\d*)$",
      "type": [
        "integer",
        "string"
      ],
      "description": "Sequential incident number from the source platform. Used in human-readable summaries and gamebook tracking.",
      "format": "int32"
    },
    "incident_title": {
      "type": [
        "null",
        "string"
      ],
      "description": "Human-readable incident title from the source platform. Used in summaries and audit logs."
    },
    "trigger_type": {
      "description": "How the agent run was triggered. OnQueue (background): subject to per-severity Gamebooks capability gating — submissions are rejected for severities where Gamebooks is not enabled. ManualInvestigateAndRespond (operator-requested): always allowed to submit gamebooks regardless of capability settings.",
      "$ref": "#/$defs/AgentTriggerType"
    },
    "playbooks": {
      "type": [
        "null",
        "array"
      ],
      "items": {
        "$ref": "#/$defs/AgentToolPlaybook"
      },
      "description": "Ordered playbook actions to run as part of this gamebook. Each entry binds a playbook from the registered catalog to its target entity. Must contain at least one entry — empty arrays are rejected."
    }
  },
  "$defs": {
    "AgentToolPlaybook": {
      "type": "object",
      "properties": {
        "playbook_id": {
          "type": [
            "null",
            "string"
          ],
          "description": "ID of a playbook from the registered playbook catalog. Unknown IDs cause the entire submission to fail — there is no partial-success mode."
        },
        "entity_id": {
          "type": [
            "null",
            "string"
          ],
          "description": "Stable identifier of the target entity. MUST be the entity object's `id` property — NEVER `aadUserId`, `DeviceId`, `FileHash`, or any other entity-specific property. Using the wrong identifier here will cause the playbook to act on the wrong target or fail."
        },
        "affected_entity": {
          "type": [
            "null",
            "string"
          ],
          "description": "Display name of the target entity (e.g. UPN for a user, hostname for a device). Shown in human-readable summaries and audit logs."
        },
        "sequence": {
          "pattern": "^-?(?:0|[1-9]\\d*)$",
          "type": [
            "integer",
            "string"
          ],
          "description": "Run order within the gamebook, starting at 1. Lower numbers execute first. Use this to express dependencies — e.g., scan endpoint (sequence 1) before isolate endpoint (sequence 2) on the same device. Sequence is independent per entity: playbooks targeting different entities run in parallel groups.",
          "format": "int32"
        },
        "internet_message_id": {
          "type": [
            "null",
            "string"
          ],
          "description": "OPTIONAL — for the 'deleteemail' playbook only. RFC 2822 internet-message-id of the email to delete (the Message-ID header value, typically including angle brackets, e.g. '<abc-123@contoso.com>'). Read it verbatim from the incident's email entity — do not strip the brackets or invent it. When supplied together with user_object_id (or user_principal_name) the playbook deletes that exact message from the user's mailbox and skips incident-entity resolution entirely. Leave null for other playbooks or to fall back to entity-based resolution."
        },
        "user_object_id": {
          "type": [
            "null",
            "string"
          ],
          "description": "OPTIONAL — for the 'deleteemail' playbook only. Azure AD object id (GUID) of the mailbox owner whose inbox holds the email. Read it from the incident's recipient user entity (its aadUserId) — never invent it. Preferred over user_principal_name. Supply alongside internet_message_id to delete the message directly without entity-graph resolution."
        },
        "user_principal_name": {
          "type": [
            "null",
            "string"
          ],
          "description": "OPTIONAL — for the 'deleteemail' playbook only. User principal name (UPN, e.g. 'user@contoso.com') of the mailbox owner, used when the object id is unavailable; the server resolves it to an object id via the directory. Read it from the incident's user entity. Supply user_object_id instead when you have it."
        }
      }
    },
    "AgentTriggerType": {
      "enum": [
        "OnQueue",
        "ManualInvestigateOnly",
        "ManualInvestigateAndRespond"
      ],
      "description": "Define the type of the agent trigger that identifies the behaviour of the agent"
    }
  }
}