naylence-agent-sdk-ts / BackgroundTaskAgent

Abstract Class: BackgroundTaskAgent<StateT>

Defined in: src/naylence/agent/background-task-agent.ts:227

Base class for agents that execute long-running background tasks.

Unlike BaseAgent which runs tasks synchronously in startTask, BackgroundTaskAgent starts tasks in the background and streams status updates to subscribers. This is ideal for work that takes significant time.

Remarks

Lifecycle:

Client calls startTask, which returns immediately with WORKING status
runBackgroundTask executes asynchronously
Status updates are queued and delivered to subscribers
Task completes with COMPLETED, FAILED, or CANCELED status

Completed tasks are cached briefly for late subscribers to retrieve final status.

Example


import {
  BackgroundTaskAgent,
  TaskSendParams,
  TaskState,
} from '@naylence/agent-sdk';
 
class SlowAgent extends BackgroundTaskAgent {
  protected async runBackgroundTask(params: TaskSendParams): Promise<string> {
    // Report progress
    await this.updateTaskState(params.id, TaskState.WORKING);
 
    // Do expensive work
    await someSlowOperation();
 
    // Return value becomes the task result
    return 'done';
  }
}
 
const agent = new SlowAgent('slow-worker', {
  maxTaskLifetimeMs: 60_000, // 1 minute timeout
});
await agent.serve('fame://slow-worker');

Extends

BaseAgent<StateT>

Type Parameters

Type Parameter	Default type	Description
`StateT` extends `BaseAgentState`	`BaseAgentState`	The state model type, defaults to BaseAgentState.

Accessors

address

Get Signature


get address(): FameAddress | null;

Defined in: src/naylence/agent/base-agent.ts:496

The address this agent is registered at.

Returns

FameAddress | null

Inherited from

BaseAgent.address

capabilities

Get Signature


get capabilities(): string[];

Defined in: src/naylence/agent/base-agent.ts:480

Capabilities advertised by this agent. Includes the standard agent capability by default.

Returns

string[]

Inherited from

BaseAgent.capabilities

name

Get Signature


get name(): string | null;

Defined in: src/naylence/agent/base-agent.ts:485

The agent’s name.

Returns

string | null

Inherited from

BaseAgent.name

spec

Get Signature


get spec(): Record<string, unknown>;

Defined in: src/naylence/agent/base-agent.ts:489

Returns metadata about this agent (address, capabilities, etc.).

Returns

Record<string, unknown>

Inherited from

BaseAgent.spec

state

Get Signature


get state(): StateContext<StateT>;

Defined in: src/naylence/agent/base-agent.ts:665

State context for lock-protected state access.

Remarks

Prefer using BaseAgent.withState for simpler access patterns.

Throws

Error if no state model is configured.

Returns

StateContext<StateT>

Inherited from

BaseAgent.state

storageProvider

Get Signature


get storageProvider(): StorageProvider;

Defined in: src/naylence/agent/base-agent.ts:509

Storage provider for state persistence.

Throws

Error if no storage provider is available.

Returns

StorageProvider

Inherited from

BaseAgent.storageProvider

rpcRegistry

Get Signature


get static rpcRegistry(): ReadonlyMap<string, RpcRegistryEntry>;

Defined in: node_modules/@naylence/runtime/dist/types/naylence/fame/service/rpc.d.ts:14

Returns

ReadonlyMap<string, RpcRegistryEntry>

Inherited from

BaseAgent.rpcRegistry

Methods

aserve()


aserve(address: string | FameAddress, options: AgentServeOptions | undefined): Promise<void>;

Defined in: src/naylence/agent/base-agent.ts:1078

Starts serving this agent at the given address.

Parameters

Parameter	Type	Description
`address`	`string` \| `FameAddress`	The address to serve at (e.g., ‘fame://my-agent’).
`options`	`AgentServeOptions` \| `undefined`	Serve options including log level and fabric config.

Returns

Promise<void>

Remarks

In Node.js, the agent listens for SIGINT/SIGTERM to shut down gracefully. The method returns when the agent stops serving.

Inherited from

BaseAgent.aserve

authenticate()


authenticate(_credentials: unknown): boolean;

Defined in: src/naylence/agent/base-agent.ts:917

Validates authentication credentials.

Parameters

Parameter	Type
`_credentials`	`unknown`

Returns

boolean

True if authentication succeeds.

Inherited from

BaseAgent.authenticate

cancelTask()


cancelTask(params: {
  id: string;
  metadata?: Metadata | null;
}): Promise<{
  artifacts?:   | {
     append?: boolean | null;
     description?: string | null;
     index: number;
     lastChunk?: boolean | null;
     metadata?: Metadata | null;
     name?: string | null;
     parts: (
        | {
        metadata?: Metadata | null;
        text: string;
        type: "text";
      }
        | {
        file: {
           bytes?: string | null;
           mimeType?: string | null;
           name?: string | null;
           uri?: string | null;
        };
        metadata?: Metadata | null;
        type: "file";
      }
        | {
        data: Metadata;
        metadata?: Metadata | null;
        type: "data";
     })[];
   }[]
     | null;
  history?:   | {
     metadata?: Metadata | null;
     parts: (
        | {
        metadata?: Metadata | null;
        text: string;
        type: "text";
      }
        | {
        file: {
           bytes?: string | null;
           mimeType?: string | null;
           name?: string | null;
           uri?: string | null;
        };
        metadata?: Metadata | null;
        type: "file";
      }
        | {
        data: Metadata;
        metadata?: Metadata | null;
        type: "data";
     })[];
     role: "user" | "agent";
   }[]
     | null;
  id: string;
  metadata?: Metadata | null;
  sessionId?: string | null;
  status: {
     message?:   | {
        metadata?: Metadata | null;
        parts: (
           | {
           metadata?: Metadata | null;
           text: string;
           type: "text";
         }
           | {
           file: {
              bytes?: string | null;
              mimeType?: string | null;
              name?: string | null;
              uri?: string | null;
           };
           metadata?: Metadata | null;
           type: "file";
         }
           | {
           data: Metadata;
           metadata?: Metadata | null;
           type: "data";
        })[];
        role: "user" | "agent";
      }
        | null;
     state: TaskState;
     timestamp: Date;
  };
}>;

Defined in: src/naylence/agent/background-task-agent.ts:601

Cancels a running task.

Sets the task state to CANCELED. Does not interrupt runBackgroundTask, but prevents further state updates.

Parameters

Parameter	Type	Description
`params`	{ `id`: `string`; `metadata?`: `Metadata` \| `null`; }	Parameters including the task ID.
`params.id`	`string`	-
`params.metadata?`	`Metadata` \| `null`	-

Returns

Promise<{ artifacts?: | { append?: boolean | null; description?: string | null; index: number; lastChunk?: boolean | null; metadata?: Metadata | null; name?: string | null; parts: ( | { metadata?: Metadata | null; text: string; type: "text"; } | { file: { bytes?: string | null; mimeType?: string | null; name?: string | null; uri?: string | null; }; metadata?: Metadata | null; type: "file"; } | { data: Metadata; metadata?: Metadata | null; type: "data"; })[]; }[] | null; history?: | { metadata?: Metadata | null; parts: ( | { metadata?: Metadata | null; text: string; type: "text"; } | { file: { bytes?: string | null; mimeType?: string | null; name?: string | null; uri?: string | null; }; metadata?: Metadata | null; type: "file"; } | { data: Metadata; metadata?: Metadata | null; type: "data"; })[]; role: "user" | "agent"; }[] | null; id: string; metadata?: Metadata | null; sessionId?: string | null; status: { message?: | { metadata?: Metadata | null; parts: ( | { metadata?: Metadata | null; text: string; type: "text"; } | { file: { bytes?: string | null; mimeType?: string | null; name?: string | null; uri?: string | null; }; metadata?: Metadata | null; type: "file"; } | { data: Metadata; metadata?: Metadata | null; type: "data"; })[]; role: "user" | "agent"; } | null; state: TaskState; timestamp: Date; }; }>

The task with CANCELED status.

Overrides

BaseAgent.cancelTask

clearState()


clearState(): Promise<void>;

Defined in: src/naylence/agent/base-agent.ts:714

Deletes all persisted state for this agent.

Returns

Promise<void>

Inherited from

BaseAgent.clearState

getAgentCard()


getAgentCard(): Promise<{
  authentication?:   | {
     credentials?: string | null;
     schemes: string[];
   }
     | null;
  capabilities: {
     pushNotifications: boolean;
     stateTransitionHistory: boolean;
     streaming: boolean;
  };
  defaultInputModes: string[];
  defaultOutputModes: string[];
  description?: string | null;
  documentationUrl?: string | null;
  name: string;
  provider?:   | {
     organization: string;
     url?: string | null;
   }
     | null;
  skills: {
     description?: string | null;
     examples?: string[] | null;
     id: string;
     inputModes?: string[] | null;
     name: string;
     outputModes?: string[] | null;
     tags?: string[] | null;
  }[];
  url: string;
  version: string;
}>;

Defined in: src/naylence/agent/base-agent.ts:976

Returns the agent’s card describing its capabilities and metadata.

Returns

Promise<{ authentication?: | { credentials?: string | null; schemes: string[]; } | null; capabilities: { pushNotifications: boolean; stateTransitionHistory: boolean; streaming: boolean; }; defaultInputModes: string[]; defaultOutputModes: string[]; description?: string | null; documentationUrl?: string | null; name: string; provider?: | { organization: string; url?: string | null; } | null; skills: { description?: string | null; examples?: string[] | null; id: string; inputModes?: string[] | null; name: string; outputModes?: string[] | null; tags?: string[] | null; }[]; url: string; version: string; }>

Inherited from

BaseAgent.getAgentCard

getPushNotificationConfig()


getPushNotificationConfig(_params: {
  id: string;
  metadata?: Metadata | null;
}): Promise<{
  id: string;
  pushNotificationConfig: {
     authentication?:   | {
      [key: string]: unknown;
        credentials?: string | null;
        schemes: string[];
      }
        | null;
     token?: string | null;
     url: string;
  };
}>;

Defined in: src/naylence/agent/base-agent.ts:929

Retrieves the push notification config for a task.

Parameters

Parameter	Type
`_params`	{ `id`: `string`; `metadata?`: `Metadata` \| `null`; }
`_params.id`	`string`
`_params.metadata?`	`Metadata` \| `null`

Returns

Promise<{ id: string; pushNotificationConfig: { authentication?: | { [key: string]: unknown; credentials?: string | null; schemes: string[]; } | null; token?: string | null; url: string; }; }>

Inherited from

BaseAgent.getPushNotificationConfig

getState()


getState(): Promise<StateT>;

Defined in: src/naylence/agent/base-agent.ts:702

Retrieves a snapshot of the current state.

Returns

Promise<StateT>

Remarks

Returns a point-in-time copy. For modifications, use BaseAgent.withState.

Inherited from

BaseAgent.getState

getTaskState()


getTaskState(taskId: string): Promise<TaskState>;

Defined in: src/naylence/agent/background-task-agent.ts:380

Gets the current state of a task.

Parameters

Parameter	Type	Description
`taskId`	`string`	The task identifier.

Returns

Promise<TaskState>

The current task state, or UNKNOWN if not found.

getTaskStatus()


getTaskStatus(params: {
  historyLength?: number | null;
  id: string;
  metadata?: Metadata | null;
}): Promise<{
  artifacts?:   | {
     append?: boolean | null;
     description?: string | null;
     index: number;
     lastChunk?: boolean | null;
     metadata?: Metadata | null;
     name?: string | null;
     parts: (
        | {
        metadata?: Metadata | null;
        text: string;
        type: "text";
      }
        | {
        file: {
           bytes?: string | null;
           mimeType?: string | null;
           name?: string | null;
           uri?: string | null;
        };
        metadata?: Metadata | null;
        type: "file";
      }
        | {
        data: Metadata;
        metadata?: Metadata | null;
        type: "data";
     })[];
   }[]
     | null;
  history?:   | {
     metadata?: Metadata | null;
     parts: (
        | {
        metadata?: Metadata | null;
        text: string;
        type: "text";
      }
        | {
        file: {
           bytes?: string | null;
           mimeType?: string | null;
           name?: string | null;
           uri?: string | null;
        };
        metadata?: Metadata | null;
        type: "file";
      }
        | {
        data: Metadata;
        metadata?: Metadata | null;
        type: "data";
     })[];
     role: "user" | "agent";
   }[]
     | null;
  id: string;
  metadata?: Metadata | null;
  sessionId?: string | null;
  status: {
     message?:   | {
        metadata?: Metadata | null;
        parts: (
           | {
           metadata?: Metadata | null;
           text: string;
           type: "text";
         }
           | {
           file: {
              bytes?: string | null;
              mimeType?: string | null;
              name?: string | null;
              uri?: string | null;
           };
           metadata?: Metadata | null;
           type: "file";
         }
           | {
           data: Metadata;
           metadata?: Metadata | null;
           type: "data";
        })[];
        role: "user" | "agent";
      }
        | null;
     state: TaskState;
     timestamp: Date;
  };
}>;

Defined in: src/naylence/agent/background-task-agent.ts:396

Retrieves the full status of a task.

Parameters

Parameter	Type	Description
`params`	{ `historyLength?`: `number` \| `null`; `id`: `string`; `metadata?`: `Metadata` \| `null`; }	Query parameters including the task ID.
`params.historyLength?`	`number` \| `null`	-
`params.id`	`string`	-
`params.metadata?`	`Metadata` \| `null`	-

Returns

The task with current status.

Throws

Error if the task is unknown or expired.

Overrides

BaseAgent.getTaskStatus

handleRpcRequest()


handleRpcRequest(method: string, params: Record<string, any>): Promise<any>;

Defined in: node_modules/@naylence/runtime/dist/types/naylence/fame/service/rpc.d.ts:16

Parameters

Parameter	Type
`method`	`string`
`params`	`Record`<`string`, `any`>

Returns

Promise<any>

Inherited from

BaseAgent.handleRpcRequest

onMessage()


onMessage(message: unknown): Promise<void | FameMessageResponse | null>;

Defined in: src/naylence/agent/base-agent.ts:787

Override to handle non-RPC messages.

Called when the agent receives a message that is not a JSON-RPC request. The default implementation logs a warning and returns null.

Parameters

Parameter	Type	Description
`message`	`unknown`	The decoded message payload.

Returns

Promise<void | FameMessageResponse | null>

Optional response to send back.

Inherited from

BaseAgent.onMessage

onRegister()?


optional onRegister(node: NodeLike): Promise<void>;

Defined in: src/naylence/agent/base-agent.ts:534

Parameters

Parameter	Type
`node`	`NodeLike`

Returns

Promise<void>

Inherited from

BaseAgent.onRegister

registerPushEndpoint()


registerPushEndpoint(_config: {
  id: string;
  pushNotificationConfig: {
     authentication?:   | {
      [key: string]: unknown;
        credentials?: string | null;
        schemes: string[];
      }
        | null;
     token?: string | null;
     url: string;
  };
}): Promise<{
  id: string;
  pushNotificationConfig: {
     authentication?:   | {
      [key: string]: unknown;
        credentials?: string | null;
        schemes: string[];
      }
        | null;
     token?: string | null;
     url: string;
  };
}>;

Defined in: src/naylence/agent/base-agent.ts:922

Registers a push notification endpoint for task updates.

Parameters

Parameter	Type
`_config`	{ `id`: `string`; `pushNotificationConfig`: { `authentication?`: \| { [`key`: `string`]: `unknown`; `credentials?`: `string` \| `null`; `schemes`: `string`[]; } \| `null`; `token?`: `string` \| `null`; `url`: `string`; }; }
`_config.id`	`string`
`_config.pushNotificationConfig`	{ `authentication?`: \| { [`key`: `string`]: `unknown`; `credentials?`: `string` \| `null`; `schemes`: `string`[]; } \| `null`; `token?`: `string` \| `null`; `url`: `string`; }
`_config.pushNotificationConfig.authentication?`	\| { [`key`: `string`]: `unknown`; `credentials?`: `string` \| `null`; `schemes`: `string`[]; } \| `null`
`_config.pushNotificationConfig.token?`	`string` \| `null`
`_config.pushNotificationConfig.url`	`string`

Returns

Inherited from

BaseAgent.registerPushEndpoint

runTask()


runTask(_payload: Payload, _id: string | null): Promise<unknown>;

Defined in: src/naylence/agent/base-agent.ts:1008

Override to implement task execution logic.

This is the primary extension point for agent behavior. Return the task result or throw an error to fail the task.

Parameters

Parameter	Type	Description
`_payload`	`Payload`	The task payload.
`_id`	`string` \| `null`	Optional task identifier.

Returns

Promise<unknown>

The task result.

Throws

UnsupportedOperationException if not overridden.

Example


async runTask(payload: Payload): Promise<string> {
  const input = typeof payload === 'string' ? payload : '';
  return `Hello, ${input}!`;
}

Inherited from

BaseAgent.runTask

serve()


serve(address: string | FameAddress, options: AgentServeOptions): Promise<void>;

Defined in: src/naylence/agent/agent.ts:612

Alias for Agent.aserve.

Parameters

Parameter	Type	Description
`address`	`string` \| `FameAddress`	The address to serve at.
`options`	`AgentServeOptions`	Serve options.

Returns

Promise<void>

Inherited from

BaseAgent.serve

startTask()


startTask(params: {
  acceptedOutputModes?: string[] | null;
  historyLength?: number | null;
  id: string;
  message: {
     metadata?: Metadata | null;
     parts: (
        | {
        metadata?: Metadata | null;
        text: string;
        type: "text";
      }
        | {
        file: {
           bytes?: string | null;
           mimeType?: string | null;
           name?: string | null;
           uri?: string | null;
        };
        metadata?: Metadata | null;
        type: "file";
      }
        | {
        data: Metadata;
        metadata?: Metadata | null;
        type: "data";
     })[];
     role: "user" | "agent";
  };
  metadata?: Metadata | null;
  pushNotification?:   | {
     authentication?:   | {
      [key: string]: unknown;
        credentials?: string | null;
        schemes: string[];
      }
        | null;
     token?: string | null;
     url: string;
   }
     | null;
  sessionId: string;
}): Promise<{
  artifacts?:   | {
     append?: boolean | null;
     description?: string | null;
     index: number;
     lastChunk?: boolean | null;
     metadata?: Metadata | null;
     name?: string | null;
     parts: (
        | {
        metadata?: Metadata | null;
        text: string;
        type: "text";
      }
        | {
        file: {
           bytes?: string | null;
           mimeType?: string | null;
           name?: string | null;
           uri?: string | null;
        };
        metadata?: Metadata | null;
        type: "file";
      }
        | {
        data: Metadata;
        metadata?: Metadata | null;
        type: "data";
     })[];
   }[]
     | null;
  history?:   | {
     metadata?: Metadata | null;
     parts: (
        | {
        metadata?: Metadata | null;
        text: string;
        type: "text";
      }
        | {
        file: {
           bytes?: string | null;
           mimeType?: string | null;
           name?: string | null;
           uri?: string | null;
        };
        metadata?: Metadata | null;
        type: "file";
      }
        | {
        data: Metadata;
        metadata?: Metadata | null;
        type: "data";
     })[];
     role: "user" | "agent";
   }[]
     | null;
  id: string;
  metadata?: Metadata | null;
  sessionId?: string | null;
  status: {
     message?:   | {
        metadata?: Metadata | null;
        parts: (
           | {
           metadata?: Metadata | null;
           text: string;
           type: "text";
         }
           | {
           file: {
              bytes?: string | null;
              mimeType?: string | null;
              name?: string | null;
              uri?: string | null;
           };
           metadata?: Metadata | null;
           type: "file";
         }
           | {
           data: Metadata;
           metadata?: Metadata | null;
           type: "data";
        })[];
        role: "user" | "agent";
      }
        | null;
     state: TaskState;
     timestamp: Date;
  };
}>;

Defined in: src/naylence/agent/background-task-agent.ts:291

Starts a background task.

Returns immediately with WORKING status. The task executes asynchronously via BackgroundTaskAgent.runBackgroundTask.

Parameters

Parameter	Type	Description
`params`	{ `acceptedOutputModes?`: `string`[] \| `null`; `historyLength?`: `number` \| `null`; `id`: `string`; `message`: { `metadata?`: `Metadata` \| `null`; `parts`: ( \| { `metadata?`: `Metadata` \| `null`; `text`: `string`; `type`: `"text"`; } \| { `file`: { `bytes?`: `string` \| `null`; `mimeType?`: `string` \| `null`; `name?`: `string` \| `null`; `uri?`: `string` \| `null`; }; `metadata?`: `Metadata` \| `null`; `type`: `"file"`; } \| { `data`: `Metadata`; `metadata?`: `Metadata` \| `null`; `type`: `"data"`; })[]; `role`: `"user"` \| `"agent"`; }; `metadata?`: `Metadata` \| `null`; `pushNotification?`: \| { `authentication?`: \| { [`key`: `string`]: `unknown`; `credentials?`: `string` \| `null`; `schemes`: `string`[]; } \| `null`; `token?`: `string` \| `null`; `url`: `string`; } \| `null`; `sessionId`: `string`; }	Task parameters.
`params.acceptedOutputModes?`	`string`[] \| `null`	-
`params.historyLength?`	`number` \| `null`	-
`params.id`	`string`	-
`params.message`	{ `metadata?`: `Metadata` \| `null`; `parts`: ( \| { `metadata?`: `Metadata` \| `null`; `text`: `string`; `type`: `"text"`; } \| { `file`: { `bytes?`: `string` \| `null`; `mimeType?`: `string` \| `null`; `name?`: `string` \| `null`; `uri?`: `string` \| `null`; }; `metadata?`: `Metadata` \| `null`; `type`: `"file"`; } \| { `data`: `Metadata`; `metadata?`: `Metadata` \| `null`; `type`: `"data"`; })[]; `role`: `"user"` \| `"agent"`; }	-
`params.message.metadata?`	`Metadata` \| `null`	-
`params.message.parts`	( \| { `metadata?`: `Metadata` \| `null`; `text`: `string`; `type`: `"text"`; } \| { `file`: { `bytes?`: `string` \| `null`; `mimeType?`: `string` \| `null`; `name?`: `string` \| `null`; `uri?`: `string` \| `null`; }; `metadata?`: `Metadata` \| `null`; `type`: `"file"`; } \| { `data`: `Metadata`; `metadata?`: `Metadata` \| `null`; `type`: `"data"`; })[]	-
`params.message.role`	`"user"` \| `"agent"`	-
`params.metadata?`	`Metadata` \| `null`	-
`params.pushNotification?`	\| { `authentication?`: \| { [`key`: `string`]: `unknown`; `credentials?`: `string` \| `null`; `schemes`: `string`[]; } \| `null`; `token?`: `string` \| `null`; `url`: `string`; } \| `null`	-
`params.sessionId`	`string`	-

Returns

The task with initial WORKING status.

Overrides

BaseAgent.startTask

subscribeToTaskUpdates()


subscribeToTaskUpdates(params: {
  acceptedOutputModes?: string[] | null;
  historyLength?: number | null;
  id: string;
  message: {
     metadata?: Metadata | null;
     parts: (
        | {
        metadata?: Metadata | null;
        text: string;
        type: "text";
      }
        | {
        file: {
           bytes?: string | null;
           mimeType?: string | null;
           name?: string | null;
           uri?: string | null;
        };
        metadata?: Metadata | null;
        type: "file";
      }
        | {
        data: Metadata;
        metadata?: Metadata | null;
        type: "data";
     })[];
     role: "user" | "agent";
  };
  metadata?: Metadata | null;
  pushNotification?:   | {
     authentication?:   | {
      [key: string]: unknown;
        credentials?: string | null;
        schemes: string[];
      }
        | null;
     token?: string | null;
     url: string;
   }
     | null;
  sessionId: string;
}): AsyncIterable<TaskEvent>;

Defined in: src/naylence/agent/background-task-agent.ts:526

Subscribes to updates for a task.

Returns an async iterable that yields status and artifact events. For completed tasks, yields the cached final status if still available.

Parameters

Parameter	Type	Description
`params`	{ `acceptedOutputModes?`: `string`[] \| `null`; `historyLength?`: `number` \| `null`; `id`: `string`; `message`: { `metadata?`: `Metadata` \| `null`; `parts`: ( \| { `metadata?`: `Metadata` \| `null`; `text`: `string`; `type`: `"text"`; } \| { `file`: { `bytes?`: `string` \| `null`; `mimeType?`: `string` \| `null`; `name?`: `string` \| `null`; `uri?`: `string` \| `null`; }; `metadata?`: `Metadata` \| `null`; `type`: `"file"`; } \| { `data`: `Metadata`; `metadata?`: `Metadata` \| `null`; `type`: `"data"`; })[]; `role`: `"user"` \| `"agent"`; }; `metadata?`: `Metadata` \| `null`; `pushNotification?`: \| { `authentication?`: \| { [`key`: `string`]: `unknown`; `credentials?`: `string` \| `null`; `schemes`: `string`[]; } \| `null`; `token?`: `string` \| `null`; `url`: `string`; } \| `null`; `sessionId`: `string`; }	Task parameters including the task ID.
`params.acceptedOutputModes?`	`string`[] \| `null`	-
`params.historyLength?`	`number` \| `null`	-
`params.id`	`string`	-
`params.message`	{ `metadata?`: `Metadata` \| `null`; `parts`: ( \| { `metadata?`: `Metadata` \| `null`; `text`: `string`; `type`: `"text"`; } \| { `file`: { `bytes?`: `string` \| `null`; `mimeType?`: `string` \| `null`; `name?`: `string` \| `null`; `uri?`: `string` \| `null`; }; `metadata?`: `Metadata` \| `null`; `type`: `"file"`; } \| { `data`: `Metadata`; `metadata?`: `Metadata` \| `null`; `type`: `"data"`; })[]; `role`: `"user"` \| `"agent"`; }	-
`params.message.metadata?`	`Metadata` \| `null`	-
`params.message.parts`	( \| { `metadata?`: `Metadata` \| `null`; `text`: `string`; `type`: `"text"`; } \| { `file`: { `bytes?`: `string` \| `null`; `mimeType?`: `string` \| `null`; `name?`: `string` \| `null`; `uri?`: `string` \| `null`; }; `metadata?`: `Metadata` \| `null`; `type`: `"file"`; } \| { `data`: `Metadata`; `metadata?`: `Metadata` \| `null`; `type`: `"data"`; })[]	-
`params.message.role`	`"user"` \| `"agent"`	-
`params.metadata?`	`Metadata` \| `null`	-
`params.pushNotification?`	\| { `authentication?`: \| { [`key`: `string`]: `unknown`; `credentials?`: `string` \| `null`; `schemes`: `string`[]; } \| `null`; `token?`: `string` \| `null`; `url`: `string`; } \| `null`	-
`params.sessionId`	`string`	-

Returns

AsyncIterable<TaskEvent>

Async iterable of task events.

Overrides

BaseAgent.subscribeToTaskUpdates

unsubscribeTask()


unsubscribeTask(params: {
  id: string;
  metadata?: Metadata | null;
}): Promise<void>;

Defined in: src/naylence/agent/background-task-agent.ts:584

Cancels a task subscription.

Parameters

Parameter	Type	Description
`params`	{ `id`: `string`; `metadata?`: `Metadata` \| `null`; }	Parameters including the task ID.
`params.id`	`string`	-
`params.metadata?`	`Metadata` \| `null`	-

Returns

Promise<void>

Overrides

BaseAgent.unsubscribeTask

updateTaskArtifact()


updateTaskArtifact(taskId: string, artifact: {
  append?: boolean | null;
  description?: string | null;
  index: number;
  lastChunk?: boolean | null;
  metadata?: Metadata | null;
  name?: string | null;
  parts: (
     | {
     metadata?: Metadata | null;
     text: string;
     type: "text";
   }
     | {
     file: {
        bytes?: string | null;
        mimeType?: string | null;
        name?: string | null;
        uri?: string | null;
     };
     metadata?: Metadata | null;
     type: "file";
   }
     | {
     data: Metadata;
     metadata?: Metadata | null;
     type: "data";
  })[];
}): Promise<void>;

Defined in: src/naylence/agent/background-task-agent.ts:501

Emits an artifact for a running task.

Artifacts are delivered to subscribers as TaskArtifactUpdateEvents.

Parameters

Parameter	Type	Description
`taskId`	`string`	The task identifier.
`artifact`	{ `append?`: `boolean` \| `null`; `description?`: `string` \| `null`; `index`: `number`; `lastChunk?`: `boolean` \| `null`; `metadata?`: `Metadata` \| `null`; `name?`: `string` \| `null`; `parts`: ( \| { `metadata?`: `Metadata` \| `null`; `text`: `string`; `type`: `"text"`; } \| { `file`: { `bytes?`: `string` \| `null`; `mimeType?`: `string` \| `null`; `name?`: `string` \| `null`; `uri?`: `string` \| `null`; }; `metadata?`: `Metadata` \| `null`; `type`: `"file"`; } \| { `data`: `Metadata`; `metadata?`: `Metadata` \| `null`; `type`: `"data"`; })[]; }	The artifact to emit.
`artifact.append?`	`boolean` \| `null`	-
`artifact.description?`	`string` \| `null`	-
`artifact.index`	`number`	-
`artifact.lastChunk?`	`boolean` \| `null`	-
`artifact.metadata?`	`Metadata` \| `null`	-
`artifact.name?`	`string` \| `null`	-
`artifact.parts`	( \| { `metadata?`: `Metadata` \| `null`; `text`: `string`; `type`: `"text"`; } \| { `file`: { `bytes?`: `string` \| `null`; `mimeType?`: `string` \| `null`; `name?`: `string` \| `null`; `uri?`: `string` \| `null`; }; `metadata?`: `Metadata` \| `null`; `type`: `"file"`; } \| { `data`: `Metadata`; `metadata?`: `Metadata` \| `null`; `type`: `"data"`; })[]	-

Returns

Promise<void>

updateTaskState()


updateTaskState(
   taskId: string, 
   state: TaskState, 
   message?: 
  | {
  metadata?: Metadata | null;
  parts: (
     | {
     metadata?: Metadata | null;
     text: string;
     type: "text";
   }
     | {
     file: {
        bytes?: string | null;
        mimeType?: string | null;
        name?: string | null;
        uri?: string | null;
     };
     metadata?: Metadata | null;
     type: "file";
   }
     | {
     data: Metadata;
     metadata?: Metadata | null;
     type: "data";
  })[];
  role: "user" | "agent";
}
| null): Promise<boolean>;

Defined in: src/naylence/agent/background-task-agent.ts:426

Updates the state of a running task.

Call this from BackgroundTaskAgent.runBackgroundTask to report progress. Status updates are delivered to subscribers.

Parameters

Parameter	Type	Description
`taskId`	`string`	The task identifier.
`state`	`TaskState`	The new task state.
`message?`	\| { `metadata?`: `Metadata` \| `null`; `parts`: ( \| { `metadata?`: `Metadata` \| `null`; `text`: `string`; `type`: `"text"`; } \| { `file`: { `bytes?`: `string` \| `null`; `mimeType?`: `string` \| `null`; `name?`: `string` \| `null`; `uri?`: `string` \| `null`; }; `metadata?`: `Metadata` \| `null`; `type`: `"file"`; } \| { `data`: `Metadata`; `metadata?`: `Metadata` \| `null`; `type`: `"data"`; })[]; `role`: `"user"` \| `"agent"`; } \| `null`	Optional message with details.

Returns

Promise<boolean>

True if the update was applied, false if the task is already terminal.

withState()


withState<T>(callback: (state: StateT) => Promise<T>): Promise<T>;

Defined in: src/naylence/agent/base-agent.ts:692

Executes a callback with exclusive access to the agent’s state.

State changes are automatically persisted after the callback completes.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type	Description
`callback`	(`state`: `StateT`) => `Promise`<`T`>	Function receiving the current state.

Returns

Promise<T>

The callback’s return value.

Example


const count = await this.withState(async (state) => {
  state.count += 1;
  return state.count;
});

Inherited from

BaseAgent.withState

broadcast()


static broadcast(
   this: typeof Agent, 
   addresses: (string | FameAddress)[], 
   payload: Payload, 
options: AgentRunManyOptions): Promise<[string, any][]>;

Defined in: src/naylence/agent/agent.ts:499

Sends the same payload to multiple agents.

Parameters

Parameter	Type	Default value	Description
`this`	typeof `Agent`	`undefined`	-
`addresses`	(`string` \| `FameAddress`)[]	`undefined`	List of agent addresses.
`payload`	`Payload`	`null`	Payload to send to all agents.
`options`	`AgentRunManyOptions`	`{}`	Execution options.

Returns

Promise<[string, any][]>

Array of [address, result|error] tuples.

Inherited from

BaseAgent.broadcast

fromHandler()


static fromHandler(handler: AgentTaskHandler): Promise<Agent>;

Defined in: src/naylence/agent/agent.ts:471

Creates an agent from a simple handler function.

Parameters

Parameter	Type	Description
`handler`	`AgentTaskHandler`	Function that processes task payloads.

Returns

Promise<Agent>

A new agent instance wrapping the handler.

Remarks

Useful for quick prototyping without defining a full agent class.

Inherited from

BaseAgent.fromHandler

remote()


static remote<TAgent>(this: typeof Agent, options: AgentRemoteOptions): AgentProxy<TAgent>;

Defined in: src/naylence/agent/agent.ts:400

Creates a proxy for communicating with a remote agent.

Type Parameters

Type Parameter
`TAgent` extends `Agent`

Parameters

Parameter	Type	Description
`this`	typeof `Agent`	-
`options`	`AgentRemoteOptions`	Remote agent options.

Returns

AgentProxy<TAgent>

A proxy for the remote agent.

Remarks

Provide exactly one of address or capabilities in the options.

Example


const proxy = Agent.remote<EchoAgent>({ address: 'fame://echo' });
const result = await proxy.runTask('hello');

Throws

Error if both or neither of address/capabilities are provided.

Inherited from

BaseAgent.remote

remoteByAddress()


static remoteByAddress<TAgent>(
   this: typeof Agent, 
   address: string | FameAddress, 
   options: {
  fabric?: FameFabric;
}): AgentProxy<TAgent>;

Defined in: src/naylence/agent/agent.ts:431

Creates a proxy for a remote agent by its address.

Type Parameters

Type Parameter
`TAgent` extends `Agent`

Parameters

Parameter	Type	Description
`this`	typeof `Agent`	-
`address`	`string` \| `FameAddress`	The target agent’s address.
`options`	{ `fabric?`: `FameFabric`; }	Optional fabric configuration.
`options.fabric?`	`FameFabric`	-

Returns

AgentProxy<TAgent>

A proxy for the remote agent.

Inherited from

BaseAgent.remoteByAddress

remoteByCapabilities()


static remoteByCapabilities<TAgent>(
   this: typeof Agent, 
   capabilities: string[], 
   options: {
  fabric?: FameFabric;
}): AgentProxy<TAgent>;

Defined in: src/naylence/agent/agent.ts:450

Creates a proxy for a remote agent by required capabilities.

Type Parameters

Type Parameter
`TAgent` extends `Agent`

Parameters

Parameter	Type	Description
`this`	typeof `Agent`	-
`capabilities`	`string`[]	Required capabilities for discovery.
`options`	{ `fabric?`: `FameFabric`; }	Optional fabric configuration.
`options.fabric?`	`FameFabric`	-

Returns

AgentProxy<TAgent>

A proxy for a matching remote agent.

Inherited from

BaseAgent.remoteByCapabilities

runMany()


static runMany<TAgent>(
   this: typeof Agent, 
   targets: Targets, 
options: AgentRunManyOptions): Promise<[string, any][]>;

Defined in: src/naylence/agent/agent.ts:518

Runs tasks on multiple agents with individual payloads.

Type Parameters

Type Parameter
`TAgent` extends `Agent`

Parameters

Parameter	Type	Description
`this`	typeof `Agent`	-
`targets`	`Targets`	Iterable of [address, payload] pairs.
`options`	`AgentRunManyOptions`	Execution options.

Returns

Promise<[string, any][]>

Array of [address, result|error] tuples.

Inherited from

BaseAgent.runMany