Structure Run Events

Structure Run Events#

Running a Structure will result in Events being created for that Structure Run. Events are used to report data about the progress of your Structure Run. There are two types of Events: SYSTEM Events and USER Events.

For information about the Events APIs, check out the Events API docs .

Event Types#

System Events#

The Gen AI Builder Structure Runtime manages the lifecycle of your Structure Run. To communicate near real-time updates about the status of your Structure Run, the Cloud will emit SYSTEM Events.

The following types of SYSTEM Events are emitted:

  1. StructureRunStarting

  2. StructureRunRunning

  3. StructureRunCompleted

  4. StructureRunError

StructureRunStarting#

This Event indicates that your Structure code has been successfully loaded in the Runtime.

Example Event body:

{
    "event_id": "12345678-1909-4900-8eca-6f7d82da9fdc",
    "timestamp": 1726096542.71688,
    "type": "StructureRunStarting",
    "payload": {
        "status": "STARTING"
    },
    "created_at": "2024-09-11T23:15:42.834783Z",
    "origin": "SYSTEM",
    "structure_run": "12345678-e125-4c38-b67f-02b82aa443ce"
}

StructureRunRunning#

This Event indicates that your Structure code is now executing.

Example Event body:

{
    "event_id": "22345678-1909-4900-8eca-6f7d82da9fdc",
    "timestamp": 1726096548.683578,
    "type": "StructureRunRunning",
    "payload": {
        "status": "RUNNING",
        "started_at": "2024-09-11T23:15:47"
    },
    "created_at": "2024-09-11T23:15:48.787162Z",
    "origin": "SYSTEM",
    "structure_run": "12345678-e125-4c38-b67f-02b82aa443ce"
}

StructureRunCompleted#

This Event indicates that your Structure code has exited.

Example Event body:

{
    "event_id": "32345678-f277-4f12-939f-707804f2fdf0",
    "timestamp": 1726096554.70717,
    "type": "StructureRunCompleted",
    "payload": {
        "status": "SUCCEEDED",
        "started_at": "2024-09-11T23:15:47",
        "completed_at": "2024-09-11T23:15:50",
        "status_detail": {
            "reason": "Completed",
            "message": null,
            "exit_code": 0
        }
    },
    "created_at": "2024-09-11T23:15:54.754921Z",
    "origin": "SYSTEM",
    "structure_run": "12345678-e125-4c38-b67f-02b82aa443ce"
}

StructureRunError#

This Event indicates that your Structure Run encountered an Error from the Gen AI Builder Runtime.

Example Event body:

{
    "event_id": "42345678-f277-4f12-939f-707804f2fdf0",
    "timestamp": 1726096555.70717,
    "type": "StructureRunError",
    "payload": {
        "status": "ERROR",
        "status_detail": {
            "error": "Error message"
        }
    },
    "created_at": "2024-09-11T23:15:54.754921Z",
    "origin": "SYSTEM",
    "structure_run": "12345678-e125-4c38-b67f-02b82aa443ce"
}

User Events#

USER Events are any Events emitted by your Structure code to the Events API. The recommended approach for emitting those Events is to make use of the Gen AI Builder Event Listener Driver in the Gen AI Builder SDK.

For a full example of Structure code that makes use of that driver, refer to the Managed Structure Template .

Structure Run Output#

In order for Gen AI Builder to populate the output field for your Structure Run, you must send a USER Event of type FinishStructureRunEvent .

By using the Gen AI Builder Event Listener Driver and an Event Bus that emits that Event type in your Structure code, the Cloud will automatically populate your Structure Run’s output.

Example Client Event Listener#

For an example of client code listening to Structure Run Events, check out the example client in the Managed Structure Template .

Contents