Skip to main content

Class: Agent

Defined in: livelink.clients/livelink.agent/sources/Agent.ts:245

A headless 3dverse agent.

Instantiate this class to create an agent that attaches to one or more sessions of a scene and controls them programmatically. The attachment policy is fixed at construction via the AgentConfig:

  • the attachment mode (see AgentMode),
  • an optional watch loop polling the session list and joining sessions as they appear,
  • an optional leave-on-condition policy.

Each session the agent attaches to gets its own Livelink. Observe the lifecycle through the typed events the agent dispatches (see AgentEvents); every session event carries its livelink. The agent is driven by composition — there is nothing to subclass.

Example:

const agent = new Agent({
  config: {
    scene_id: "...",
    token: "...",
    mode: "join-all",
    watch: { interval_seconds: 10 },
    leave_on_condition: { after_seconds: 60 },
  },
});

agent.addEventListener("on-session-ready", async event => {
  const entity = await event.livelink.scene.findEntity({ entity_uuid: "..." });
  // control the scene...
});

await agent.start();

Extends​

Constructors​

Constructor​

new Agent(config: {
  config: {
     scene_id: UUID;
     token: string;
     mode?: "join" | "start" | "join-or-start" | "join-all" | "manual";
     is_transient?: boolean;
     session_options?: Record<string, boolean>;
     session_selector?: (__namedParameters: {
        sessions: SessionInfo[];
     }) => SessionInfo | null;
     watch?: {
        interval_seconds?: number;
     };
     leave_on_condition?: {
        after_seconds: number;
        agent_roster_id?: UUID;
        should_stay?: (params: {
           livelink: Livelink;
           other_clients: readonly Client[];
        }) => boolean | Promise<boolean>;
     };
     headless_client?: {
        updatesPerSecond?: number;
        broadcastsPerSecond?: number;
     };
     onProgress?: (stage: LivelinkConnectionStage, info: {
        session_id?: UUID;
     }) => void;
  };
}): Agent;

Defined in: livelink.clients/livelink.agent/sources/Agent.ts:335

Parameters​

ParameterTypeDescription
config{ config: { scene_id: UUID; token: string; mode?: "join" | "start" | "join-or-start" | "join-all" | "manual"; is_transient?: boolean; session_options?: Record<string, boolean>; session_selector?: (__namedParameters: { sessions: SessionInfo[]; }) => SessionInfo | null; watch?: { interval_seconds?: number; }; leave_on_condition?: { after_seconds: number; agent_roster_id?: UUID; should_stay?: (params: { livelink: Livelink; other_clients: readonly Client[]; }) => boolean | Promise<boolean>; }; headless_client?: { updatesPerSecond?: number; broadcastsPerSecond?: number; }; onProgress?: (stage: LivelinkConnectionStage, info: { session_id?: UUID; }) => void; }; }The immutable configuration of the agent.
config.config{ scene_id: UUID; token: string; mode?: "join" | "start" | "join-or-start" | "join-all" | "manual"; is_transient?: boolean; session_options?: Record<string, boolean>; session_selector?: (__namedParameters: { sessions: SessionInfo[]; }) => SessionInfo | null; watch?: { interval_seconds?: number; }; leave_on_condition?: { after_seconds: number; agent_roster_id?: UUID; should_stay?: (params: { livelink: Livelink; other_clients: readonly Client[]; }) => boolean | Promise<boolean>; }; headless_client?: { updatesPerSecond?: number; broadcastsPerSecond?: number; }; onProgress?: (stage: LivelinkConnectionStage, info: { session_id?: UUID; }) => void; }-
config.config.scene_idUUIDThe unique identifier of the scene to run.
config.config.tokenstringThe authentication token.
config.config.mode?"join" | "start" | "join-or-start" | "join-all" | "manual"The strategy used to attach to sessions of the scene. Defaults to "join-or-start".
config.config.is_transient?booleanWhether sessions created by the agent are transient. Transient sessions are temporary and changes are not saved. Only used by the "start" and "join-or-start" modes.
config.config.session_options?Record<string, boolean>Options for creating the session. Only used by the "start" and "join-or-start" modes.
config.config.session_selector?(__namedParameters: { sessions: SessionInfo[]; }) => SessionInfo | nullA callback that selects a session from a list of candidate sessions. Only used by the "join" and "join-or-start" modes.
config.config.watch?{ interval_seconds?: number; }Poll the session list regularly and join sessions that appear. Only valid with the "join" and "join-all" modes.
config.config.watch.interval_seconds?numberThe polling interval in seconds. Defaults to 10.
config.config.leave_on_condition?{ after_seconds: number; agent_roster_id?: UUID; should_stay?: (params: { livelink: Livelink; other_clients: readonly Client[]; }) => boolean | Promise<boolean>; }Leave a session when the configured leave condition is met for the given duration.
config.config.leave_on_condition.after_secondsnumberThe number of seconds the condition must persist before leaving the session.
config.config.leave_on_condition.agent_roster_id?UUIDThe UUID of the agent_roster entity, under which each agent registers a marker entity named after its own client id (see Session.client_id). When set, the default should_stay predicate uses the roster's children to identify which of the other clients are agents. If the entity is not found in the scene, an error is logged and the check falls back to plain other-client presence.
config.config.leave_on_condition.should_stay?(params: { livelink: Livelink; other_clients: readonly Client[]; }) => boolean | Promise<boolean>Determines whether the agent should stay in the session based on the given livelink and the other clients connected. Defaults to stay while a non-agent client is present (see agent_roster_id), or any other client is present when roster is absent.
config.config.headless_client?{ updatesPerSecond?: number; broadcastsPerSecond?: number; }Options for the headless client update loop started in each session.
config.config.headless_client.updatesPerSecond?number-
config.config.headless_client.broadcastsPerSecond?number-
config.config.onProgress?(stage: LivelinkConnectionStage, info: { session_id?: UUID; }) => voidCallback for tracking connection progress of each session the agent attaches to.

Returns​

Agent

Overrides​

TypedEventTarget.constructor

Accessors​

config​

Get Signature​

get config(): Readonly<{
  scene_id: UUID;
  token: string;
  mode?: "join" | "start" | "join-or-start" | "join-all" | "manual";
  is_transient?: boolean;
  session_options?: Record<string, boolean>;
  session_selector?: (__namedParameters: {
     sessions: SessionInfo[];
  }) => SessionInfo | null;
  watch?: {
     interval_seconds?: number;
  };
  leave_on_condition?: {
     after_seconds: number;
     agent_roster_id?: UUID;
     should_stay?: (params: {
        livelink: Livelink;
        other_clients: readonly Client[];
     }) => boolean | Promise<boolean>;
  };
  headless_client?: {
     updatesPerSecond?: number;
     broadcastsPerSecond?: number;
  };
  onProgress?: (stage: LivelinkConnectionStage, info: {
     session_id?: UUID;
  }) => void;
}>;

Defined in: livelink.clients/livelink.agent/sources/Agent.ts:289

The configuration this agent was built with, fixed at construction. Read-only: an agent's attach policy and update rates are settled before it starts.

Returns​

Readonly<{ scene_id: UUID; token: string; mode?: "join" | "start" | "join-or-start" | "join-all" | "manual"; is_transient?: boolean; session_options?: Record<string, boolean>; session_selector?: (__namedParameters: { sessions: SessionInfo[]; }) => SessionInfo | null; watch?: { interval_seconds?: number; }; leave_on_condition?: { after_seconds: number; agent_roster_id?: UUID; should_stay?: (params: { livelink: Livelink; other_clients: readonly Client[]; }) => boolean | Promise<boolean>; }; headless_client?: { updatesPerSecond?: number; broadcastsPerSecond?: number; }; onProgress?: (stage: LivelinkConnectionStage, info: { session_id?: UUID; }) => void; }>

Get Signature​

get livelinks(): readonly Livelink[];

Defined in: livelink.clients/livelink.agent/sources/Agent.ts:296

The livelinks of all sessions the agent is currently attached to.

Returns​

readonly Livelink[]

session​

Get Signature​

get session(): Session;

Defined in: livelink.clients/livelink.agent/sources/Agent.ts:305

The session the agent is connected to. Only valid when the agent is attached to exactly one session, throws otherwise. Convenience for single-session agents; use livelinks otherwise.

Returns​

Session

scene​

Get Signature​

get scene(): Scene;

Defined in: livelink.clients/livelink.agent/sources/Agent.ts:314

The scene managed by the agent. Only valid when the agent is attached to exactly one session, throws otherwise. Convenience for single-session agents; use livelinks otherwise.

Returns​

Scene

Methods​

getLivelink(__namedParameters: {
  session_id: UUID;
}): Livelink | null;

Defined in: livelink.clients/livelink.agent/sources/Agent.ts:349

Get the livelink of a session the agent is attached to, or null if not attached to it.

Parameters​

ParameterType
__namedParameters{ session_id: UUID; }
__namedParameters.session_idUUID

Returns​

Livelink | null

start()​

start(): Promise<void>;

Defined in: livelink.clients/livelink.agent/sources/Agent.ts:361

Attach to sessions according to the configured mode and start the agent. Resolves once the initial attachment wave is done; the watch loop, if enabled, keeps running in the background.

Returns​

Promise<void>

Throws​

If the agent is already started, or if the initial attachment fails. A failed start leaves the agent stopped: any session attached by the failed wave is left behind.

stop()​

stop(): Promise<void>;

Defined in: livelink.clients/livelink.agent/sources/Agent.ts:448

Stop the agent: leave all sessions (with reason "stopped") and stop the watch loop. Resolves once all sessions have been left; do any post-stop cleanup after it returns. No-op if the agent is not started.

Dispatches on-stopped. The agent may also stop itself, dispatching the same event with is_automatic set — see AgentMode.

Returns​

Promise<void>

leave()​

leave(__namedParameters: {
  session_id: UUID;
}): Promise<void>;

Defined in: livelink.clients/livelink.agent/sources/Agent.ts:504

Leave a single session deliberately. The watch loop never rejoins it on its own; call Agent.join to rejoin it later.

Parameters​

ParameterType
__namedParameters{ session_id: UUID; }
__namedParameters.session_idUUID

Returns​

Promise<void>

join()​

join(__namedParameters: {
  session_id: UUID;
}): Promise<void>;

Defined in: livelink.clients/livelink.agent/sources/Agent.ts:516

Join a session on demand, in particular to rejoin one previously left with Agent.leave. Clears any prior leave marker so the watch loop treats the session normally afterwards. No-op if the agent is not started, or if it is already attached to, or attaching, the session.

Parameters​

ParameterType
__namedParameters{ session_id: UUID; }
__namedParameters.session_idUUID

Returns​

Promise<void>

Throws​

If no session with the given id is running the agent's scene.

addEventListener()​

addEventListener<_EventName>(
   event_name: _EventName,
   listener: (event: AgentEvents[_EventName]) => void,
   options?: boolean | AddEventListenerOptions): void;

Defined in: livelink.clients/livelink.base/sources/TypedEventTarget.ts:10

Type Parameters​

Type Parameter
_EventName extends | "on-session-created" | "on-session-joined" | "on-session-ready" | "on-session-left" | "on-error" | "on-stopped"

Parameters​

ParameterType
event_name_EventName
listener(event: AgentEvents[_EventName]) => void
options?boolean | AddEventListenerOptions

Returns​

void

Inherited from​

TypedEventTarget.addEventListener

removeEventListener()​

removeEventListener<_EventName>(
   event_name: _EventName,
   listener: (event: AgentEvents[_EventName]) => void,
   options?: boolean | EventListenerOptions): void;

Defined in: livelink.clients/livelink.base/sources/TypedEventTarget.ts:21

Type Parameters​

Type Parameter
_EventName extends | "on-session-created" | "on-session-joined" | "on-session-ready" | "on-session-left" | "on-error" | "on-stopped"

Parameters​

ParameterType
event_name_EventName
listener(event: AgentEvents[_EventName]) => void
options?boolean | EventListenerOptions

Returns​

void

Inherited from​

TypedEventTarget.removeEventListener