lt.agents

lt.agents manages agents: named automations that react to events and run on schedules. Each agent has subscriptions that map an event topic to a reaction. See Agents and events.

list

const result = await lt.agents.list({ status: 'active', limit: 25 });

List agents with optional filters. Each agent includes subscription_count and sub_topics[].

Parameters

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

Returns: LTApiResult<{ agents: LTAgent[], total: number }>

get

const result = await lt.agents.get({ id: 'health-monitor' });

Get one agent with its stats.

Parameters

Field	Type	Required	Description
id	string	Yes	Agent id

Returns: LTApiResult<LTAgent & { stats: LTAgentStats }>. 404 if not found.

create

const result = await lt.agents.create({
  id: 'health-monitor',
  description: 'Watches for workflow failures',
  goals: 'Detect failures early',
  rules: 'Never auto-restart',
  status: 'active',
  knowledge_domain: 'system-health',
  behaviors: {
    schedules: [{ cron: '*/5 * * * *', workflow_type: 'basicEcho' }],
  },
});

Create an agent. The id is the agent’s readable name (kebab-case, URL-safe) and is its primary key.

Parameters

Field	Type	Required	Description
id	string	Yes	Agent name and primary key
description	string	No	What the agent does
goals	string	No	The agent’s goals
rules	string	No	Rules the agent follows
status	string	No	Initial status
knowledge_domain	string	No	Knowledge domain the agent reads and writes
behaviors	object	No	Behaviors, such as schedules: [{ cron, workflow_type }]

Returns: LTApiResult<LTAgent> with status 201. 409 if the id already exists.

update

await lt.agents.update({ id: 'health-monitor', status: 'paused' });

Partially update an agent. Changing status or behaviors restarts its event subscriptions and cron schedules.

Parameters

Field	Type	Required	Description
id	string	Yes	Agent id
...		No	Any field accepted by create

Returns: LTApiResult<LTAgent>. 404 if not found.

delete

await lt.agents.delete({ id: 'health-monitor' });

Delete an agent. Its subscriptions and schedules stop. Knowledge and workflow history are kept.

Parameters

Field	Type	Required	Description
id	string	Yes	Agent id

Returns: LTApiResult<{ deleted: true }>. 404 if not found.

listSubscriptions

const result = await lt.agents.listSubscriptions({ agentId: 'health-monitor' });

List an agent’s event subscriptions.

Parameters

Field	Type	Required	Description
agentId	string	Yes	Agent id

Returns: LTApiResult<{ subscriptions: AgentSubscription[] }>

createSubscription

const result = await lt.agents.createSubscription({
  agentId: 'health-monitor',
  topic: 'system.workflow.*.failed',
  reaction_type: 'durable',
  workflow_type: 'basicEcho',
  input_mapping: {
    data: { error: '{event.status}', workflowId: '{event.workflowId}' },
  },
});

Subscribe an agent to an event topic.

Parameters

Field	Type	Required	Description
agentId	string	Yes	Agent id
topic	string	Yes	Event topic pattern (* matches one token, > matches the rest)
reaction_type	string	Yes	durable, pipeline, mcp_query or capability
workflow_type	string	For durable	Workflow name
pipeline_id	string	For pipeline	YAML workflow UUID
mcp_prompt	string	For mcp_query	Query prompt
server_id	string	For capability	MCP server UUID
tool_name	string	For capability	MCP tool name
input_mapping	object	No	Event-to-envelope field mapping
filter	object	No	Shallow match against event.data
execute_as	string	No	Identity override

Returns: LTApiResult<AgentSubscription> with status 201.

updateSubscription

await lt.agents.updateSubscription({
  id: 'subscription-uuid',
  topic: 'app.vendor.*.error',
});

Partially update a subscription. The agent’s triggers reload.

Parameters

Field	Type	Required	Description
id	string	Yes	Subscription id
...		No	Any field accepted by createSubscription

Returns: LTApiResult<AgentSubscription>. 404 if not found.

deleteSubscription

await lt.agents.deleteSubscription({ id: 'subscription-uuid' });

Delete a subscription. The agent’s triggers reload.

Parameters

Field	Type	Required	Description
id	string	Yes	Subscription id

Returns: LTApiResult<{ deleted: true }>. 404 if not found.