Class: AgentHandle

Defined in: packages/sdk/src/backend/agents.ts:220

A handle bound to one agent.

Constructors

Constructor

new AgentHandle(base, headers, name): AgentHandle

Defined in: packages/sdk/src/backend/agents.ts:221

Parameters

base

string

headers

Record<string, string>

name

string

Returns

AgentHandle

Properties

name

readonly name: string

Defined in: packages/sdk/src/backend/agents.ts:224

Methods

addRule()

addRule(opts): Promise<AgentRule>

Defined in: packages/sdk/src/backend/agents.ts:295

Parameters

opts

action?

string

condition

string

priority?

number

type

RuleType

Returns

Promise<AgentRule>

addTool()

addTool(opts): Promise<AgentTool>

Defined in: packages/sdk/src/backend/agents.ts:261

Parameters

opts

allowedHosts?

string[]

authHeader?

string

Policy extras (M2). secretRef names a project secret (see setSecret).

description?

string

http

{ method?: string; url: string; }

http.method?

string

http.url

string

name

string

parameters?

Record<string, unknown>

ratePerMin?

number

secretRef?

string

Returns

Promise<AgentTool>

attachKnowledge()

attachKnowledge(kb): Promise<{ attached: string; }>

Defined in: packages/sdk/src/backend/agents.ts:248

Parameters

kb

string

Returns

Promise<{ attached: string; }>

chat()

chat(messages, opts?): Promise<AgentChatResult>

Defined in: packages/sdk/src/backend/agents.ts:319

Run a turn: retrieve → rules → grounded answer with citations + trace. Pass memory: { userId } to make the turn memory-native: relevant memories for that user are recalled before answering and the exchange is persisted after (scoped to this agent + project).

Parameters

messages

ChatMessage[]

opts?

conversationId?

string

Thread this turn into a conversation (groups runs; filter listRuns).

memory?

{ extract?: string[]; persist?: boolean; recall?: boolean; topK?: number; userId: string; }

memory.extract?

string[]

Record schemas to extract from the turn (typed-memory.md §2.6). Stored rows return on the response as records_extracted. Max 3.

memory.persist?

boolean

memory.recall?

boolean

memory.topK?

number

memory.userId

string

topK?

number

Returns

Promise<AgentChatResult>

chatStream()

chatStream(messages, opts?): AsyncGenerator<string, void, unknown>

Defined in: packages/sdk/src/backend/agents.ts:389

Stream one agent turn as text deltas over the OpenAI-compatible endpoint (POST /v1/chat/completions, stream: true) — so you can render token-by-token without pulling in the openai package:

for await (const delta of agent.chatStream(messages)) process.stdout.write(delta);

The turn runs the full server-side pipeline; streaming is buffer-then-stream, so guardrails/risk-hold still gate before the first delta. The typed extras (ui_actions/citations/escalated) that don't fit the OpenAI schema arrive on the final frame — pass onFinal to capture them, or use chat.

Parameters

messages

ChatMessage[]

opts?

onFinal?

(extras) => void

signal?

AbortSignal

Returns

AsyncGenerator<string, void, unknown>

deleteRule()

deleteRule(id): Promise<{ deleted: string; }>

Defined in: packages/sdk/src/backend/agents.ts:309

Parameters

id

string

Returns

Promise<{ deleted: string; }>

deleteTool()

deleteTool(id): Promise<{ deleted: string; }>

Defined in: packages/sdk/src/backend/agents.ts:289

Parameters

id

string

Returns

Promise<{ deleted: string; }>

detachKnowledge()

detachKnowledge(kb): Promise<{ detached: string; }>

Defined in: packages/sdk/src/backend/agents.ts:254

Parameters

kb

string

Returns

Promise<{ detached: string; }>

getRun()

getRun(id): Promise<AgentRun>

Defined in: packages/sdk/src/backend/agents.ts:368

Fetch one persisted turn's full trace (M4).

Parameters

id

string

Returns

Promise<AgentRun>

listRules()

listRules(): Promise<AgentRule[]>

Defined in: packages/sdk/src/backend/agents.ts:304

Returns

Promise<AgentRule[]>

listRuns()

listRuns(opts?): Promise<AgentRunSummary[]>

Defined in: packages/sdk/src/backend/agents.ts:353

List this agent's recent persisted turns, newest first (M4).

Parameters

opts?

conversationId?

string

limit?

number

offset?

number

Returns

Promise<AgentRunSummary[]>

listTools()

listTools(): Promise<AgentTool[]>

Defined in: packages/sdk/src/backend/agents.ts:284

Returns

Promise<AgentTool[]>