Skip to Content
Naylence Docs are in active development. Share feedback in Discord.
ReferenceAgent APITypeScript ReferenceClassesBaseAgent

naylence-agent-sdk-ts

naylence-agent-sdk-ts / BaseAgent

Class: BaseAgent<StateT>

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

Standard implementation of the Agent protocol.

Provides built-in state management, message handling, and task lifecycle support. Extend this class and override BaseAgent.runTask to implement your agent logic.

Remarks

BaseAgent handles:

  • JSON-RPC message routing
  • State persistence with optional Zod validation
  • Task creation from runTask results
  • Graceful shutdown via SIGINT/SIGTERM

For background/async task execution, use BackgroundTaskAgent instead.

Example

import { BaseAgent, Payload, BaseAgentState } from '@naylence/agent-sdk';
import { z } from 'zod';
 
const CounterSchema = z.object({ count: z.number() });
 
class CounterState extends BaseAgentState {
  static readonly schema = CounterSchema;
  count = 0;
}
 
class CounterAgent extends BaseAgent<CounterState> {
  static STATE_MODEL = CounterState;
 
  async runTask(payload: Payload): Promise<number> {
    return await this.withState(async (state) => {
      state.count += 1;
      return state.count;
    });
  }
}
 
const agent = new CounterAgent('counter');
await agent.serve('fame://counter');

Extends

Extended by

Type Parameters

Type ParameterDefault typeDescription
StateT extends BaseAgentStateBaseAgentStateThe state model type, defaults to BaseAgentState.

Implements

  • Registerable

Constructors

Constructor

new BaseAgent<StateT>(name: string | null, options: BaseAgentOptions<StateT>): BaseAgent<StateT>;

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

Creates a new BaseAgent.

Parameters

ParameterTypeDefault valueDescription
namestring | nullnullAgent name. Defaults to snake_case of the class name.
optionsBaseAgentOptions<StateT>{}Configuration options for state and storage.

Returns

BaseAgent<StateT>

Overrides

Agent.constructor

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

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[]

Overrides

Agent.capabilities

name

Get Signature

get name(): string | null;

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

The agent’s name.

Returns

string | null

Overrides

Agent.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>

Overrides

Agent.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>

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

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

Agent.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

ParameterTypeDescription
addressstring | FameAddressThe address to serve at (e.g., ‘fame://my-agent’).
optionsAgentServeOptions | undefinedServe 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.

Overrides

Agent.aserve

authenticate()

authenticate(_credentials: unknown): boolean;

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

Validates authentication credentials.

Parameters

ParameterType
_credentialsunknown

Returns

boolean

True if authentication succeeds.

Overrides

Agent.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/base-agent.ts:971

Requests cancellation of a running task.

Parameters

ParameterType
_params{ id: string; metadata?: Metadata | null; }
_params.idstring
_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 updated status.

Overrides

Agent.cancelTask

clearState()

clearState(): Promise<void>;

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

Deletes all persisted state for this agent.

Returns

Promise<void>

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; }>

Overrides

Agent.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

ParameterType
_params{ id: string; metadata?: Metadata | null; }
_params.idstring
_params.metadata?Metadata | null

Returns

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

Overrides

Agent.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.

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/base-agent.ts:982

Retrieves the current status of a task.

Parameters

ParameterType
_params{ historyLength?: number | null; id: string; metadata?: Metadata | null; }
_params.historyLength?number | null
_params.idstring
_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; }; }>

Overrides

Agent.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

ParameterType
methodstring
paramsRecord<string, any>

Returns

Promise<any>

Inherited from

Agent.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

ParameterTypeDescription
messageunknownThe decoded message payload.

Returns

Promise<void | FameMessageResponse | null>

Optional response to send back.

onRegister()?

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

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

Parameters

ParameterType
nodeNodeLike

Returns

Promise<void>

Implementation of

Registerable.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

ParameterType
_config{ id: string; pushNotificationConfig: { authentication?: | { [key: string]: unknown; credentials?: string | null; schemes: string[]; } | null; token?: string | null; url: string; }; }
_config.idstring
_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.urlstring

Returns

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

Overrides

Agent.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

ParameterTypeDescription
_payloadPayloadThe task payload.
_idstring | nullOptional 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}!`;
}

Overrides

Agent.runTask

serve()

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

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

Alias for Agent.aserve.

Parameters

ParameterTypeDescription
addressstring | FameAddressThe address to serve at.
optionsAgentServeOptionsServe options.

Returns

Promise<void>

Inherited from

Agent.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/base-agent.ts:1028

Initiates a task and returns its status.

Parameters

ParameterTypeDescription
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 message and metadata.
params.acceptedOutputModes?string[] | null-
params.historyLength?number | null-
params.idstring-
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.sessionIdstring-

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 completed task with result.

Remarks

If you override BaseAgent.runTask, this method automatically creates a Task from the result. Override this method for custom task lifecycle management.

Throws

Error if neither startTask nor runTask is implemented.

Overrides

Agent.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<
  | {
  final: boolean;
  id: string;
  metadata?: Metadata | null;
  status: {
     message?:   | {
        metadata?: Metadata | null;
        parts: (
           | {
           metadata?: Metadata | null;
           text: string;
           type: "text";
         }
           | {
           file: {
              bytes?: ... | ... | ...;
              mimeType?: ... | ... | ...;
              name?: ... | ... | ...;
              uri?: ... | ... | ...;
           };
           metadata?: Metadata | null;
           type: "file";
         }
           | {
           data: Metadata;
           metadata?: Metadata | null;
           type: "data";
        })[];
        role: "user" | "agent";
      }
        | null;
     state: TaskState;
     timestamp: Date;
  };
}
  | {
  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";
     })[];
  };
  id: string;
  metadata?: Metadata | null;
}>;

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

Subscribes to real-time updates for a task.

Parameters

ParameterTypeDescription
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.idstring-
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.sessionIdstring-

Returns

AsyncIterable< | { final: boolean; id: string; metadata?: Metadata | null; status: { message?: | { metadata?: Metadata | null; parts: ( | { metadata?: Metadata | null; text: string; type: "text"; } | { file: { bytes?: … | … | …; mimeType?: … | … | …; name?: … | … | …; uri?: … | … | …; }; metadata?: Metadata | null; type: "file"; } | { data: Metadata; metadata?: Metadata | null; type: "data"; })[]; role: "user" | "agent"; } | null; state: TaskState; timestamp: Date; }; } | { 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"; })[]; }; id: string; metadata?: Metadata | null; }>

An async iterable of status and artifact update events.

Overrides

Agent.subscribeToTaskUpdates

unsubscribeTask()

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

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

Cancels a task subscription.

Parameters

ParameterType
_params{ id: string; metadata?: Metadata | null; }
_params.idstring
_params.metadata?Metadata | null

Returns

Promise<unknown>

Overrides

Agent.unsubscribeTask

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

ParameterTypeDescription
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;
});

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

ParameterTypeDefault valueDescription
thistypeof Agentundefined-
addresses(string | FameAddress)[]undefinedList of agent addresses.
payloadPayloadnullPayload to send to all agents.
optionsAgentRunManyOptions{}Execution options.

Returns

Promise<[string, any][]>

Array of [address, result|error] tuples.

Inherited from

Agent.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

ParameterTypeDescription
handlerAgentTaskHandlerFunction 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

Agent.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

ParameterTypeDescription
thistypeof Agent-
optionsAgentRemoteOptionsRemote 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

Agent.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

ParameterTypeDescription
thistypeof Agent-
addressstring | FameAddressThe target agent’s address.
options{ fabric?: FameFabric; }Optional fabric configuration.
options.fabric?FameFabric-

Returns

AgentProxy<TAgent>

A proxy for the remote agent.

Inherited from

Agent.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

ParameterTypeDescription
thistypeof Agent-
capabilitiesstring[]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

Agent.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

ParameterTypeDescription
thistypeof Agent-
targetsTargetsIterable of [address, payload] pairs.
optionsAgentRunManyOptionsExecution options.

Returns

Promise<[string, any][]>

Array of [address, result|error] tuples.

Inherited from

Agent.runMany

Last updated on
BackgroundTaskAgentBaseAgentState