Skip to main content

Interface: Agent

Defined in: packages/agentos/src/api/agent.ts:666

A stateful agent instance returned by agent.

Properties​

learning?​

optional learning: AgentLearning

Defined in: packages/agentos/src/api/agent.ts:700

The agent's learning layer as its host reads it. Set only with runtime: 'gmi' and learning on.

Methods​

close()​

close(): Promise<void>

Defined in: packages/agentos/src/api/agent.ts:696

Releases all in-memory session state held by this agent.

Returns​

Promise<void>


export()​

export(metadata?, options?): AgentExportConfig

Defined in: packages/agentos/src/api/agent.ts:708

Exports the agent's configuration as a portable object. Secrets are redacted unless options.redactSecrets is false.

Parameters​

metadata?​

Optional human-readable metadata to attach.

author?​

string

description?​

string

name?​

string

tags?​

string[]

options?​

ExportAgentConfigOptions

Redaction options.

Returns​

AgentExportConfig

A portable AgentExportConfig object.


exportJSON()​

exportJSON(metadata?, options?): string

Defined in: packages/agentos/src/api/agent.ts:716

Exports the agent's configuration as a pretty-printed JSON string. Secrets are redacted unless options.redactSecrets is false.

Parameters​

metadata?​

Optional human-readable metadata to attach.

author?​

string

description?​

string

name?​

string

tags?​

string[]

options?​

ExportAgentConfigOptions

Redaction options.

Returns​

string

JSON string.


generate()​

generate(prompt, opts?): Promise<GenerateTextResult>

Defined in: packages/agentos/src/api/agent.ts:675

Generates a single reply without maintaining session history. Accepts plain text or multimodal content (text + image parts).

Parameters​

prompt​

MessageContent

User prompt as text string or MessageContent array.

opts?​

Partial<GenerateTextOptions>

Optional overrides merged on top of the agent's base options.

Returns​

Promise<GenerateTextResult>

The complete generation result.


getAvatarBindings()​

getAvatarBindings(): AvatarBindingInputs & Record<string, unknown>

Defined in: packages/agentos/src/api/agent.ts:718

Read current avatar binding state (auto-populated from mood/voice/relationship).

Returns​

AvatarBindingInputs & Record<string, unknown>


session()​

session(id?, options?): AgentSession

Defined in: packages/agentos/src/api/agent.ts:692

Returns (or creates) a named AgentSession with its own conversation history.

Parameters​

id?​

string

Optional session ID. A unique ID is generated when omitted.

options?​

AgentSessionOptions

The session's user; see AgentSessionOptions.

Returns​

AgentSession

The session object for this ID.


setAvatarBindingOverrides()​

setAvatarBindingOverrides(overrides): void

Defined in: packages/agentos/src/api/agent.ts:720

Inject game-specific binding overrides (healthBand, combatMode, etc.).

Parameters​

overrides​

Record<string, unknown>

Returns​

void


stream()​

stream(prompt, opts?): StreamTextResult

Defined in: packages/agentos/src/api/agent.ts:684

Streams a single reply without maintaining session history. Accepts plain text or multimodal content (text + image parts).

Parameters​

prompt​

MessageContent

User prompt as text string or MessageContent array.

opts?​

Partial<GenerateTextOptions>

Optional overrides merged on top of the agent's base options.

Returns​

StreamTextResult

A StreamTextResult.


usage()​

usage(sessionId?): Promise<AgentOSUsageAggregate>

Defined in: packages/agentos/src/api/agent.ts:694

Returns persisted usage totals for the whole agent or a single session.

Parameters​

sessionId?​

string

Returns​

Promise<AgentOSUsageAggregate>


voiceSession()?​

optional voiceSession(request): Promise<ManagedVoiceSession>

Defined in: packages/agentos/src/api/agent.ts:722

Prepares the configured scoped voice call; present only with voice.session.

Parameters​

request​

Omit<StartVoiceSession, "agent">

Returns​

Promise<ManagedVoiceSession>