Agents

Agents.invoke sends a prompt to a target agent and returns that agent’s reply after a complete turn: its persona, skills and tools, processors, and governance all run. For a bare model call with no agent, use AI. The reply is returned, not delivered: nothing reaches a channel unless the target’s tools send it or you pass result.text to Channels.send. Available in tools, jobs, webhooks, triggers, processors, and workflow code steps. The target must be in your agent’s organization. The supervision members (Agents.list, logs, runs, data, versions, persona, source and env) read another agent of your organization. They work only after an org admin has granted your agent supervision over that agent; see Supervise another agent. Verified against lua-cli 3.33.0. The supervision members are live on the platform; their lua-cli types, and those of Lua.request.invokedBy, arrive in the next CLI release.

import { Agents } from 'lua-cli';

Quick example

The short form returns the reply text; the options form returns the full result.

import { Agents } from 'lua-cli';

const reply = await Agents.invoke('baseAgent_agent_1770000000000_k3xq9mz2p', 'Summarize the last order.');

const result = await Agents.invoke('baseAgent_agent_1770000000000_k3xq9mz2p', {
  prompt: 'Draft a reply to the latest order',
  threadId: 'order-4471',
  runtimeContext: 'order=4471',
});

Methods

invoke(targetAgentId, prompt)

Runs one turn with a plain prompt and returns the reply text.

Agents.invoke(targetAgentId: string, prompt: string): Promise<string>

string

required

The target’s agent id, for example baseAgent_agent_1770000000000_k3xq9mz2p. Pass this agent’s own id to invoke itself; there is no alias for the current agent. Your project’s id is agent.agentId in lua.skill.yaml and project.agentId in lua status --json --ci; lua agents --json lists every agent you can access.

string

required

The end-user message for the turn.

Returns — the reply text, after the target’s postprocessors. Example

import { Agents, env } from 'lua-cli';

const digest = await Agents.invoke(env('DIGEST_AGENT_ID') ?? '', 'Write the daily digest.');

Errors — the same as invoke(targetAgentId, input).

invoke(targetAgentId, input)

Runs one turn with full options and returns the structured result.

Agents.invoke(targetAgentId: string, input: AgentInvocationInput): Promise<AgentInvocationOutput>

string

required

The target’s agent id. See the short form.

string

Plain end-user message. Pass prompt or messages, not both.

UserContent

AI SDK v5 parts: { type: 'text', text }, { type: 'image', image, mediaType? }, { type: 'file', data, mediaType, filename? }.

string

Replaces the persona for this turn only, when an agent invokes itself. Dropped when the target is another agent, which always runs with its own persona. See What reaches another agent.

string

Extra context attached to the request, for example serialized metadata.

{ timezone?: string }

The end user’s IANA time zone, such as Africa/Nairobi. When omitted, the target uses the end user’s stored profile, then UTC. Dropped when the target is another agent.

string

Thread suffix that isolates this turn’s conversation. When omitted, the turn joins the end user’s default thread with the target, exactly like a direct message.

string

default:"agent-invocation"

The channel value the target’s code reads from Lua.request.channel. It labels the turn; it doesn’t deliver the reply anywhere. On another agent, workflow, task and trigger are replaced by agent-invocation.

string

Free-form tag stored on the message record, for example a trace id. Not a user id.

string

The end user to run the turn as. In a tool or processor the turn’s end user is used and this field isn’t needed. In a job, webhook, or trigger there is no ambient end user: pass userId to run as that end user (conversation history is stored), or omit it to run without a user identity (no history, no User profile). The user must belong to your agent’s organization. The target sees the id as Lua.request.invokedBy.delegatedUserId.

unknown

Raw payload from the source event. The target’s code reads it from Lua.request.webhook.payload for this turn; it isn’t stored.

number

default:120000

Per-call timeout in milliseconds. The calling context’s own budget caps it: a tool or processor run is walled at 180 s and a job at its own timeout, so larger values buy nothing; a webhook handler has no server-side wall, but its caller is disconnected after about 90 s.

string

A model code for this turn, when an agent invokes itself. A code the platform doesn’t approve falls back per its policy. Dropped when the target is another agent, which always runs on its own model.

Returns

AgentInvocationOutput

Show properties

string

The reply text, after the target’s postprocessors.

string

The threadId you passed; undefined when you passed none.

string

An AI SDK finish reason such as stop or length.

object

inputTokens, outputTokens, totalTokens, reasoningTokens, cachedInputTokens, each optional.

string[]

Names of the tools the target called during the turn.

Example

import { Agents, LuaWebhook, env } from 'lua-cli';

export default new LuaWebhook({
  name: 'order-shipped',
  description: 'Tell the customer their order shipped',
  async execute(event) {
    const body = (event.body ?? {}) as { orderId?: string; customerId?: string };
    if (!body.customerId) return { skipped: true };

    const result = await Agents.invoke(env('NOTIFY_AGENT_ID') ?? '', {
      prompt: `Order ${body.orderId} has shipped. Tell the customer.`,
      userId: body.customerId,
      webhookPayload: event.body,
    });
    return { text: result.text, tools: result.toolsUsed ?? [] };
  },
});

Errors — the call throws. In a deployed agent the error is an AgentInvocationError with a code and, where an HTTP status applies, a statusCode; in lua test it is a plain Error carrying the server’s message, or Agent invocation failed.

`code`	Status	When
`MISSING_TARGET_AGENT`	—	Empty target: `Target agentId is required`
`MISSING_PROMPT`	—	Neither `prompt` nor `messages`
`AGENT_DISABLED`	423	`Target agent <id> is disabled`
`PAYMENT_REQUIRED`	402	The organization has no credits for the turn
`UNAUTHORIZED`	401	`Agent invocation authentication failed`
`cross_org_invoke_denied`	403	The target is in another organization
`delegated_user_not_in_org`	403	`userId` is not a member of your agent’s organization
`PREPROCESSOR_BLOCKED`, `GOVERNANCE_BLOCKED`	—	The target’s preprocessor or governance stopped the turn; `message` is the block text
`TIMEOUT`	504	`Agent invocation timed out`
`SERVICE_UNAVAILABLE`	503	The platform could not be reached
`HTTP_ERROR`	other	Any other HTTP status: `Agent invocation failed (HTTP <status>)`
`UNEXPECTED_ERROR`	500	A failure that wasn’t an HTTP response

A userId who cannot reach the target fails with a 403, User <userId> cannot be delegated to agent <id>.

In lua test the call is made with your developer credentials: userId, model, and timeoutMs are not sent, so you are always the end user and the default timeout applies. A blocked turn is returned with finishReason set to preprocessor_blocked or governance_blocked rather than thrown; deployed agents honor all three fields and throw. Because the local call is made as you rather than as an agent, it is not treated as another agent’s turn: a systemPrompt sent to a different agent can still apply locally although a deployed agent drops it, and the target sees no Lua.request.invokedBy.

What reaches another agent

When your agent invokes a different agent, the target decides how it runs. The platform keeps only the conversation fields of your request and drops the rest:

Kept: the message (prompt or messages), threadId, runtimeContext, webhookPayload, and the reasoning effort.
Dropped: systemPrompt, model, clientContext, and every other field. A channel of workflow, task or trigger becomes agent-invocation; any other channel is kept.

The call still succeeds; the dropped fields are simply not applied, and the target runs with its own persona, model and tools. When an agent invokes itself, nothing is dropped. The target always knows who called: every turn created by Agents.invoke, including a self-invoke, carries Lua.request.invokedBy with the calling agent’s id, verified by the platform. Use it to refuse writes that did not come from someone allowed to make them; see Accept changes from a supervisor.

Supervision

An org admin can grant one agent supervision over another agent of the same organization. The grant unlocks read-only members next to invoke. Nothing in your code, your environment or a push can create a grant: without one, every member below except list fails, and list returns []. Each grant names one or more actions:

Action	Unlocks
`observe`	`logs` (without message bodies), `runs`, `data` (only the collections the grant names), `versions.list/get/diff`, `persona.versions`, `source`, `env.keys`
`observe-content`	Message bodies in `logs`. `observe` alone never returns them
`act`	The target sees `invokedBy.supervisor === true` when your agent invokes it, and `secrets.put` into the collections the grant names in `secretWriteCollections`
`preview`, `release`	`versions.preview`, `versions.promote` and `persona.activate`. Not generally available; see Preview and release

import { Agents } from 'lua-cli';

const agents = await Agents.list(); // [{ agentId, name, actions: ['observe', …] }]
const errors = await Agents.logs('baseAgent_agent_1770000000000_k3xq9mz2p', { level: 'error', limit: 20 });
const failed = await Agents.runs('baseAgent_agent_1770000000000_k3xq9mz2p').list({ status: 'failed' });
const { keys } = await Agents.env('baseAgent_agent_1770000000000_k3xq9mz2p').keys(); // names only

Every supervision call that is allowed, or refused for lack of a grant, writes a supervisor_access line to the target’s logs, where its owner reads it with lua logs (source supervision; --type supervision from the next CLI release). If that line cannot be written, the call fails. A supervising agent may make 60 supervision calls a minute. The members are refused in a turn that runs in a group conversation.

list() and get()

Agents.list(): Promise<SupervisedAgentSummary[]>
Agents.get(agentId: string): Promise<SupervisedAgentSummary & { personaVersion?: number }>

The agents of your organization other than your own, each { agentId, name?, actions }, where actions are the supervision actions your agent holds on it (empty for an agent you hold no grant on). Only an agent that holds at least one grant in the organization sees them: anyone else gets [] from list() and supervision_not_found from get(). get adds the persona version the agent serves.

logs()

Agents.logs(agentId: string, opts?: { since?: string | number; limit?: number; level?: 'debug' | 'info' | 'warn' | 'error'; logSource?: string }): Promise<SupervisionLogRow[]>

Recent log lines of the target, newest first. Needs observe.

string | number

An ISO timestamp or epoch milliseconds. Defaults to 24 hours ago; nothing older than 7 days is returned.

number

default:50

At most 100.

'debug' | 'info' | 'warn' | 'error'

Only lines of this level.

string

Only lines of this source, as in lua logs --type.

Each row is { timestamp, level?, logSource?, primitiveName?, toolName?, message? }. message, truncated to 2,000 characters, is present only when the grant also holds observe-content. No row ever carries a user id.

runs()

Agents.runs(agentId: string): {
  list(opts?: { limit?: number; status?: string; workflowId?: string }): Promise<SupervisionRunSummary[]>;
  get(runId: string): Promise<SupervisionRunSummary>;
}

The target’s workflow runs, newest first, as metadata only: { runId, workflowId?, workflowName?, status, reason?, trigger?, createdAt?, startedAt?, completedAt? }. Inputs, outputs and step results are never returned. limit defaults to 20, at most 50. Needs observe.

data()

Agents.data(agentId: string): {
  get(collection: string, entryId: string): Promise<unknown>;
  query(collection: string, filter?: Record<string, unknown>, opts?: { page?: number; limit?: number }): Promise<unknown>;
}

Read-only access to the target’s Data collections that the grant names in dataCollections. Any other collection fails with supervision_data_not_granted, whatever the target’s own code does. filter is a Lua Query filter; limit defaults to 20, at most 100. Needs observe.

versions() and persona()

Agents.versions(agentId: string): {
  list(opts?: { limit?: number; status?: SupervisionVersionStatus | SupervisionVersionStatus[]; offset?: number }): Promise<unknown>;
  get(version: number): Promise<unknown>;
  diff(from: number, to: number): Promise<unknown>;
}
Agents.persona(agentId: string): { versions(): Promise<unknown> }

The target’s agent versions and persona versions, in the same shapes as the REST routes, newest first. list returns 20 versions by default, at most 50. Needs observe. From lua-cli 3.50.0, list also takes:

SupervisionVersionStatus | SupervisionVersionStatus[]

Only versions with this status, or any of these: active, staged, superseded or deleted.

number

default:0

Versions to skip, newest first, 0 to 10,000. Use it to page past the newest 50.

const staged = await Agents.versions('base_agent-reporter').list({ status: 'staged', limit: 50 });
const older = await Agents.versions('base_agent-reporter').list({ status: ['staged', 'superseded'], limit: 50, offset: 50 });

A call with only limit answers as before. An invalid status or offset fails with supervision_bad_args. A platform that predates these options ignores them, so check each row’s status and version before you rely on the filter.

source()

Agents.source(agentId: string): {
  list(): Promise<{ files: { path: string; size?: number }[] }>;
  get(path: string): Promise<{ path: string; content: string }>;
}

The files of the target’s source backup, each up to 512 KB. Paths that look like credentials (.env*, *.pem, *.key, id_*, .npmrc, .netrc, credentials*, *.p12, *.pfx, *secret*), dot-directories and the files a backup already skips are never listed or returned. Needs observe.

env()

Agents.env(agentId: string): { keys(): Promise<{ keys: string[] }> }

The names of the target’s environment variables. Values are never returned. Needs observe.

secrets()

Agents.secrets(agentId: string): {
  put(collection: string, key: string, value: Record<string, string | number | boolean | null>): Promise<{ ok: true; id: string; fingerprint: string }>;
}

Hands the target a credential without it passing through a model. From your code (a workflow code step or a job), put writes one row into the target’s own Data: the entry of collection whose _pk field is key is replaced whole by value, with _pk set to key, or created when there is none. Later puts update the same entry. Available in lua-cli 3.50.0 and later.

// In a workflow code step or a job of the supervisor: fetch and write in the same step, return only the receipt.
const token = await fetchServiceToken(); // your own code; never a tool argument or a prompt
const receipt = await Agents.secrets('base_agent-reporter').put('reporting_api_token', 'access', {
  accessToken: token.accessToken,
  expiresAt: token.expiresAt,
});
return { fingerprint: receipt.fingerprint };

// The target reads it with its own Data access:
//   const { data } = await Data.get('reporting_api_token', { _pk: 'access' });

Needs act on the target and the collection in the grant’s secretWriteCollections, which only an org admin sets. Without it, no collection takes a secret write.
value is flat: string, finite number, boolean or null fields with plain identifier names, at most 32 fields, a string at most 8 KB and 16 KB in all. No search text is set, so the value is never embedded.
The answer never carries the value: { ok, id, fingerprint }, where fingerprint is sha256: and the first 16 hex characters of the SHA-256 of the stored row as JSON with sorted keys (_pk included). Send the target a message carrying only the fingerprint to tell it to reload a cached secret.
The collection is write-only for you: Agents.data(id).get and query refuse it, and an admin cannot also list it in dataCollections.
The target’s logs get a supervisor_access line and a secret_written line with the collection, entry id and fingerprint, never the value. A refusal gets a line with its code only.
Keep the value out of your step’s result and memory: fetch and put in one step, and return only the receipt.
Refused on your own agent, in a test session, and under lua test.

Preview and release

Not generally available. Agents.versions(id).preview(version, prompt), Agents.versions(id).promote(version, { expectActive }) and Agents.persona(id).activate(version, { expectActive }) exist in the SDK, but the platform refuses them (supervision_preview_disabled, supervision_release_disabled) unless it has been switched on for your environment. They are off by default.

Agents.versions(id).delete(version) is a release member too: it removes a superseded version, or, from lua-cli 3.50.0, a staged version that was never active, is over 24 hours old and is not the newest staged version, so an agent at its version limit can free slots. The active version and the last version are never deleted. Where they are switched on, they need a preview or release grant. A release also runs only from a live workflow step of a workflow the grant names, never from a tool, always needs expectActive (see Promote safely), is limited to 3 a day for each supervising and supervised pair, and records promotedBy: service:agent:<supervisorId> on the version.

Offline in lua test

In lua test the read members call the platform with your developer credential, so they return what you can see rather than what a grant allows. They mirror the same projections: logs without user ids or message bodies, runs as metadata, env as names only.

data, source.get, list, get and preview fail with supervision_unavailable_offline: the readable collections are part of the grant, which a developer credential cannot see.
promote, activate and versions.delete fail with supervision_release_offline_refused: a local test never changes a live agent.
secrets.put fails with supervision_offline_unsupported: it writes into a live agent’s data.

Supervision errors

Every supervision member throws a SupervisionError with a code:

`code`	When
`supervision_not_granted`	No grant with the action this member needs
`supervision_not_found`	The agent is in another organization or does not exist; the two are never told apart
`supervision_self_refused`	Your agent named itself
`supervision_data_not_granted`	`data` on a collection the grant does not name
`supervision_rate_limited`, `supervision_release_limited`	Over 60 calls a minute, or over the daily release limit
`supervision_audit_unavailable`, `supervision_unavailable`, `supervision_rate_unavailable`	The platform could not record or count the call; retry later
`supervision_room_refused`	Called in a turn in a group conversation
`supervision_bad_args`	A required argument is missing or invalid
`supervision_secret_write_not_granted`	`secrets.put` into a collection the grant does not name in `secretWriteCollections`
`supervision_secret_bad_args`	`secrets.put` with a value that is not flat or is too large; the message names the field, never the value
`supervision_secret_collection_write_only`	`data` on a collection that is in `secretWriteCollections`
`supervision_version_not_superseded`	`versions.delete` on the active version or a deleted one
`supervision_version_staged_was_active`, `supervision_version_staged_too_recent`, `supervision_version_staged_newest`	`versions.delete` on a staged version that was once active, is under 24 hours old, or is the newest staged version
`supervision_preview_disabled`, `supervision_release_disabled`	Preview or release is not switched on
`supervision_release_binding_required`, `supervision_release_binding_refused`, `supervision_expect_active_required`	A release not made from a named workflow step, or without `expectActive`
`PROMOTE_CONFLICT`, `PERSONA_ACTIVATE_CONFLICT`	`expectActive` is not the live version
`supervision_unavailable_offline`, `supervision_release_offline_refused`, `supervision_offline_unsupported`, `supervision_offline_error`	In `lua test`; see Offline

Types

AgentInvocationInput and AgentInvocationOutput have the fields listed under invoke(targetAgentId, input). They are not exported from lua-cli; declare your own variables with those fields, or let inference type the call.

SDK

CLI

REST API

Quick example

Methods

invoke(targetAgentId, prompt)

invoke(targetAgentId, input)

What reaches another agent

Supervision

list() and get()

logs()

runs()

data()

versions() and persona()

source()

env()

secrets()

Preview and release

Offline in lua test

Supervision errors

Types

See also

​Quick example

​Methods

​invoke(targetAgentId, prompt)

​invoke(targetAgentId, input)

​What reaches another agent

​Supervision

​list() and get()

​logs()

​runs()

​data()

​versions() and persona()

​source()

​env()

​secrets()

​Preview and release

​Offline in lua test

​Supervision errors

​Types

​See also

Quick example

Methods

invoke(targetAgentId, prompt)

invoke(targetAgentId, input)

What reaches another agent

Supervision

list() and get()

logs()

runs()

data()

versions() and persona()

source()

env()

secrets()

Preview and release

Offline in lua test

Supervision errors

Types

See also