Agents

An agent automation is a persona that reacts to events and runs workflows on schedules. Each automation has an identity, a motivation (goals and rules), event subscriptions, cron schedules and a knowledge domain.

All endpoints require authentication. Creating, updating and deleting agents and subscriptions requires builder access (superadmin or the engineer role).

Configuring an agent or subscription also requires that the caller may act as the identity it runs as (its execute_as, else the agent’s user_id). The act-as rule: a superadmin may act as anyone, and a caller holding an admin-type grant may act as an account that holds no superadmin grant and whose every role the caller holds at the same or higher type. A schedule or subscription with no identity runs as lt-system, and a capability subscription calls a tool with lt-system authority; only a superadmin may configure either.

See Agents and events for how automations fit together.

List agent automations

GET /api/agents

Returns agents with subscription counts and topic lists.

Query parameters

Parameter	Type	Required	Description
status	string	No	Filter by status: active, inactive, paused, error
knowledge_domain	string	No	Filter by knowledge domain
limit	number	No	Max results (default: 50)
offset	number	No	Pagination offset

Example request

curl "https://lt.acme.dev/api/agents?status=active&knowledge_domain=system-health&limit=25&offset=0" \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "agents": [
    {
      "id": "health-monitor",
      "description": "Watches for workflow failures",
      "status": "active",
      "knowledge_domain": "system-health",
      "behaviors": { "schedules": [{ "cron": "*/5 * * * *", "workflow_type": "basicEcho" }] },
      "subscription_count": 4,
      "sub_topics": ["workflow.failed", "activity.failed", "app.*.*.error", "task.failed"],
      "last_run_at": "2026-05-15T04:24:58.351Z",
      ...
    }
  ],
  "total": 3
}

Get agent automation

GET /api/agents/:id

Returns an agent with aggregated stats (knowledge entry count, escalation count).

Path parameters

Parameter	Type	Description
id	string	Agent id

Example request

curl https://lt.acme.dev/api/agents/health-monitor \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "id": "health-monitor",
  "stats": { "knowledge_count": 3, "escalation_count": 0 },
  ...
}

Create agent automation

POST /api/agents

Creates an agent automation.

Auth: Requires builder access and the act-as rule for user_id and each schedule’s identity.

Request body

Field	Type	Required	Description
id	string	Yes	Unique kebab-case identifier (e.g. health-monitor). Serves as primary key.
description	string	No	One-sentence summary
goals	string	No	Agent’s primary motivation
rules	string	No	Guardrails and constraints
status	string	No	active, inactive, paused, error (default: inactive)
user_id	string	No	Service account UUID
knowledge_domain	string	No	Knowledge domain to own
behaviors	object	No	{ schedules?: AgentSchedule[] }

Example request

curl -X POST https://lt.acme.dev/api/agents \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "health-monitor",
    "description": "Watches for workflow failures and schema drift",
    "goals": "Detect failures early, capture diagnostics",
    "rules": "Never auto-restart failed workflows",
    "status": "active",
    "knowledge_domain": "system-health",
    "behaviors": {
      "schedules": [
        { "cron": "*/5 * * * *", "workflow_type": "basicEcho", "envelope": {} }
      ]
    }
  }'

Response 201: The created agent.

Update agent automation

PUT /api/agents/:id

Partial update: include only the fields to change. Changing status or behaviors restarts the agent’s event subscriptions and cron schedules.

Auth: Same as create.

Path parameters

Parameter	Type	Description
id	string	Agent id

Request body: Any fields from create.

Example request

curl -X PUT https://lt.acme.dev/api/agents/health-monitor \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

Response 200: The updated agent.

Delete agent automation

DELETE /api/agents/:id

Permanently removes the agent. Its event subscriptions are deleted with it and its cron schedules stop. Knowledge entries and workflow history are preserved.

Auth: Requires builder access.

Path parameters

Parameter	Type	Description
id	string	Agent id

Example request

curl -X DELETE https://lt.acme.dev/api/agents/health-monitor \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{ "deleted": true }

Automation subscriptions

Subscriptions wire events to workflows. When an event matches the topic pattern, the automation invokes the configured workflow.

List subscriptions

GET /api/agents/:agentId/subscriptions

Returns the agent’s event subscriptions.

Path parameters

Parameter	Type	Description
agentId	string	Agent id

Example request

curl https://lt.acme.dev/api/agents/health-monitor/subscriptions \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{
  "subscriptions": [
    {
      "id": "uuid",
      "agent_id": "health-monitor",
      "topic": "workflow.failed",
      "filter": { "status": 422 },
      "reaction_type": "durable",
      "workflow_type": "basicEcho",
      "input_mapping": { "data": { "error": "{event.data.error}" } },
      "execute_as": null,
      "enabled": true
    }
  ]
}

Create subscription

POST /api/agents/:agentId/subscriptions

Wires an event topic to a workflow, pipeline, MCP query or tool call.

Auth: Requires builder access and the act-as rule for the subscription’s identity. A capability subscription requires superadmin.

Path parameters

Parameter	Type	Description
agentId	string	Agent id

Request body

Field	Type	Required	Description
topic	string	Yes	Event topic pattern. Supports * (one token) and > (rest of subject).
reaction_type	string	Yes	durable, pipeline, mcp_query, or capability
workflow_type	string	For durable	Registered workflow name
pipeline_id	string	For pipeline	YAML workflow UUID
mcp_prompt	string	For mcp_query	Dynamic query prompt
server_id	string	For capability	MCP server UUID
tool_name	string	For capability	MCP tool name
input_mapping	object	No	Maps event fields to the workflow envelope. Templates: {event.data.field}
filter	object	No	Shallow key-value match against event.data
execute_as	string	No	Identity override for this subscription
enabled	boolean	No	Default: true

Example request

curl -X POST https://lt.acme.dev/api/agents/health-monitor/subscriptions \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "workflow.failed",
    "reaction_type": "durable",
    "workflow_type": "basicEcho",
    "input_mapping": { "data": { "error": "{event.status}" } },
    "filter": { "status": 422 },
    "enabled": true
  }'

Response 201: The created subscription.

Update subscription

PUT /api/agents/:agentId/subscriptions/:subId

Partial update of a subscription.

Auth: Same as create.

Path parameters

Parameter	Type	Description
agentId	string	Agent id
subId	string	Subscription id

Request body: Any fields from create subscription.

Example request

curl -X PUT https://lt.acme.dev/api/agents/health-monitor/subscriptions/$SUB_ID \
  -H "Authorization: Bearer $LT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Response 200: The updated subscription.

Response 404: The subscription does not belong to the agent.

Delete subscription

DELETE /api/agents/:agentId/subscriptions/:subId

Removes a subscription.

Auth: Requires builder access.

Path parameters

Parameter	Type	Description
agentId	string	Agent id
subId	string	Subscription id

Example request

curl -X DELETE https://lt.acme.dev/api/agents/health-monitor/subscriptions/$SUB_ID \
  -H "Authorization: Bearer $LT_TOKEN"

Response 200

{ "deleted": true }