AgentSession

Arm a trigger that wakes an agent

Changed on

Arms a one-shot trigger on this session. An event trigger fires when the named entity reaches the named event; a timer trigger, not yet supported, would fire at a time or on an interval until it expires. Firing queues a message in the session's inbox and starts the agent if nothing is running. A session run locally is refused, and so is watching one, since neither a wake nor its lifecycle events reach it. A trigger registered for something that has already happened fires immediately, so a caller never has to check first. Sending the same idempotency_key to the same session again returns the trigger stored the first time.

post/agentSession/{id}/triggers

Request

  • Base URL: https://api.mabl.com
  • URL: https://api.mabl.com/agentSession/{id}/triggers
  • Auth: one of:
    • HTTP basic
    • API key in header Authorization

Path parameters

idstring required

Request body

entity_type'plan_run' | 'test_run' | 'failure_analysis' | 'agent_session'
entity_idstring
event'completed' | 'ended' | 'awaiting_input' | 'finalized'

What happened to the entity. completed applies to plan_run, test_run and failure_analysis; ended, awaiting_input and finalized apply to agent_session. Other pairs are refused.

ttl_secondsinteger

How long the trigger stays armed. Defaults to two hours.

fire_after_secondsinteger

Seconds from now until a timer fires, or until an event trigger's fallback fires. Not yet supported; setting it is refused with a 400.

interval_secondsinteger

Makes a timer repeat at this period until it expires. Not yet supported; setting it is refused with a 400.

idempotency_keystring

Makes a retry safe. The same key on the same session returns the trigger stored the first time.

Response

The trigger stored earlier under the same idempotency_key; nothing new was armed.

trigger_idstring required

Server-assigned id. The inbox message a firing writes carries it back.

agent_session_idstring required

The session this trigger wakes.

workspace_idstring required
trigger_type'event' | 'timer' required
entity_type'plan_run' | 'test_run' | 'failure_analysis' | 'agent_session'
entity_idstring

The entity an event trigger watches. For failure_analysis this is the analyzed test run's id.

event'completed' | 'ended' | 'awaiting_input' | 'finalized'

What happened to the entity. completed applies to plan_run, test_run and failure_analysis; ended, awaiting_input and finalized apply to agent_session. Other pairs are refused.

state'armed' | 'fired' | 'disarmed' required
source'registration' | 'notify_on_complete' required
idempotency_keystring

The key this trigger was stored under, when one was supplied.

registered_by_idstring required

The authenticated caller that armed it.

registered_by_agent_session_idstring

The agent session whose credential armed it, when an agent did.

created_timeinteger required
expires_atinteger required

After this time the trigger never fires.

fire_atinteger

For a timer, when it fires. For an event trigger, a fallback: it fires then if the event has not happened.

interval_secondsinteger

For a repeating timer, the period between firings until expires_at.

next_execution_targetinteger

The next time the timer sweep will consider this trigger, when it has a timer.

fired_timeinteger
fired_event_idstring

Identity of the occurrence that fired it.

disarm_reason'cancelled' | 'session_terminal' | 'session_removed'

Changes