LimAI Docs

Agent run events report the lifecycle of an agent run. Four event types share one payload shape:

Event	Fires when
`AGENT_RUN_STARTED`	An agent run transitions to `RUNNING` for the first time
`AGENT_RUN_COMPLETED`	An agent run finishes successfully
`AGENT_RUN_FAILED`	An agent run terminates with an error
`AGENT_RUN_WAITING_HUMAN`	An agent run pauses at a step that requires human input

Agent-Based Routing

Agent run events are routed to subscriptions by agent route, not deployment route. When you subscribe to any agent event you select which agents the subscription listens to; deployments are not involved in routing these events.

A subscription that includes any agent event must have at least one agent route. This mirrors document events, which must have at least one deployment route. See Webhook Setup for the routing-family model.

The payload carries fileId and deploymentId as optional context only -- they are never used to route the event:

Document-triggered runs -- fileId and deploymentId are present, pointing at the document that triggered the run.
Email-triggered runs -- fileId and deploymentId are null.

Payload Structure

Run Started

Response200

{
  "eventId": "evt_run_started_111",
  "eventType": "AGENT_RUN_STARTED",
  "timestamp": "2024-01-15T11:00:00Z",
  "organizationId": "org_xyz789",
  "projectId": "proj_abc123",
  "agentId": "agt_555",
  "runId": "run_777",
  "stepId": null,
  "fileId": "file_789ghi",
  "deploymentId": "dep_123abc",
  "data": {
    "status": "RUNNING",
    "errorMessage": null,
    "executionDurationMs": null
  }
}

Run Completed

Response200

{
  "eventId": "evt_run_completed_222",
  "eventType": "AGENT_RUN_COMPLETED",
  "timestamp": "2024-01-15T11:00:42Z",
  "organizationId": "org_xyz789",
  "projectId": "proj_abc123",
  "agentId": "agt_555",
  "runId": "run_777",
  "stepId": null,
  "fileId": "file_789ghi",
  "deploymentId": "dep_123abc",
  "data": {
    "status": "COMPLETED",
    "errorMessage": null,
    "executionDurationMs": 42000
  }
}

Run Failed

Response200

{
  "eventId": "evt_run_failed_333",
  "eventType": "AGENT_RUN_FAILED",
  "timestamp": "2024-01-15T11:01:10Z",
  "organizationId": "org_xyz789",
  "projectId": "proj_abc123",
  "agentId": "agt_555",
  "runId": "run_888",
  "stepId": null,
  "fileId": null,
  "deploymentId": null,
  "data": {
    "status": "FAILED",
    "errorMessage": "Tool call timed out",
    "executionDurationMs": 15000
  }
}

Run Waiting for Human

Response200

{
  "eventId": "evt_run_waiting_444",
  "eventType": "AGENT_RUN_WAITING_HUMAN",
  "timestamp": "2024-01-15T11:00:30Z",
  "organizationId": "org_xyz789",
  "projectId": "proj_abc123",
  "agentId": "agt_555",
  "runId": "run_777",
  "stepId": "step_999",
  "fileId": "file_789ghi",
  "deploymentId": "dep_123abc",
  "data": {
    "status": "WAITING_HUMAN",
    "errorMessage": null,
    "executionDurationMs": null
  }
}

Payload Fields

Field	Type	Description
`eventId`	string	Unique event identifier. Use for idempotency.
`eventType`	string	One of `AGENT_RUN_STARTED`, `AGENT_RUN_COMPLETED`, `AGENT_RUN_FAILED`, `AGENT_RUN_WAITING_HUMAN`
`timestamp`	ISO 8601	When the transition occurred (UTC)
`organizationId`	string	Your organization identifier
`projectId`	string	The project the agent belongs to
`agentId`	string	The agent that produced this run. Used for routing.
`runId`	string	The agent run identifier
`stepId`	string \| null	The step identifier. Set for `AGENT_RUN_WAITING_HUMAN`, otherwise null.
`fileId`	string \| null	Context only. The triggering file for document-triggered runs, null for email-triggered runs.
`deploymentId`	string \| null	Context only. The triggering deployment for document-triggered runs, null for email-triggered runs.
`data.status`	string	`"RUNNING"` \| `"WAITING_HUMAN"` \| `"COMPLETED"` \| `"FAILED"`
`data.errorMessage`	string \| null	Error description for `AGENT_RUN_FAILED`, otherwise null
`data.executionDurationMs`	number \| null	Total execution time in milliseconds, when available (set on terminal events)

Handling the Events

function handleAgentRunEvent(event) {
const { eventType, agentId, runId, fileId, data } = event

switch (eventType) {
  case "AGENT_RUN_STARTED":
    console.log(`Agent ${agentId} started run ${runId}`)
    break
  case "AGENT_RUN_WAITING_HUMAN":
    notifyReviewer(runId, event.stepId)
    break
  case "AGENT_RUN_COMPLETED":
    console.log(`Run ${runId} completed in ${data.executionDurationMs}ms`)
    if (fileId) fetchFileData(fileId).then(exportResults)
    break
  case "AGENT_RUN_FAILED":
    console.error(`Run ${runId} failed: ${data.errorMessage}`)
    break
}
}

Agent Run Events

Agent-Based Routing

Payload Structure

Run Started

Run Completed

Run Failed

Run Waiting for Human

Payload Fields

Handling the Events

On this page