Agents APIs

Build stateful agents that maintain persistent memory across interactions

While each Modus SDK offers similar capabilities, the APIs and usage may vary between languages.

Modus Agents APIs documentation is available on the following pages:

• AssemblyScript Agents APIs(this page)
• Go Agents APIs

The Modus Agents APIs allow you to create stateful agents that maintain persistent memory across interactions, survive system failures, and coordinate complex multi-step operations.

Import

To begin, import the agents namespace and Agent base class from the SDK:

import { agents, Agent, AgentInfo } from "@hypermode/modus-sdk-as"

Agent APIs

The APIs in the agents namespace are below, organized by category.

We’re constantly introducing new APIs through ongoing development with early users. Please open an issue if you have ideas on what would make Modus even more powerful for your next app!

Agent Management Functions

register

Register an agent class with the Modus runtime before it can be instantiated.

function register<T extends Agent>(): void

T · required

The agent class type that extends the Agent base class.

Agent registration must be done at the module level, outside of any function.

start

Create and start a new agent instance.

function start(agentName: string): AgentInfo

agentName · string · required

The name of the agent class to instantiate. This must match the name property returned by the agent class.

stop

Stop an agent instance. Once stopped, the agent can’t be resumed.

function stop(agentId: string): AgentInfo

agentId · string · required

The unique identifier of the agent instance to stop.

get info

Get information about a specific agent instance.

function getInfo(agentId: string): AgentInfo

agentId · string · required

The unique identifier of the agent instance.

list all

List all active agent instances.

function listAll(): AgentInfo[]

Communication Functions

send message

Send a synchronous message to an agent and wait for a response.

function sendMessage(
  agentId: string,
  messageName: string,
  data: string | null = null,
): string | null

agentId · string · required

The unique identifier of the target agent instance.

messageName · string · required

The name of the message to send to the agent.

data · string | null

Optional data payload to send with the message.

sendMessageAsync

Send an asynchronous message to an agent without waiting for a response.

function sendMessageAsync(
  agentId: string,
  messageName: string,
  data: string | null = null,
): void

agentId · string · required

The unique identifier of the target agent instance.

messageName · string · required

The name of the message to send to the agent.

data · string | null

Optional data payload to send with the message.

Agent Base Class

Agent

The base class that all agents must extend.

abstract class Agent {
  abstract get name(): string
  abstract onReceiveMessage(
    messageName: string,
    data: string | null,
  ): string | null

  getState(): string | null
  setState(data: string | null): void
  onInitialize(): void
  onSuspend(): void
  onResume(): void
  onTerminate(): void
}

name · string · required

Abstract property that must return a unique name for the agent class.

onReceiveMessage(messageName, data) · method · required

Abstract method that handles incoming messages to the agent. Must be implemented by all agent classes.

getState() · method

Optional method that returns the agent’s current state as a string for persistence. Called automatically when the agent needs to be suspended or migrated.

setState(data) · method

Optional method that restores the agent’s state from a string. Called automatically when the agent is resumed or migrated.

onInitialize() · method

Optional lifecycle method called when the agent is first created.

onSuspend() · method

Optional lifecycle method called when the agent is about to be suspended.

onResume() · method

Optional lifecycle method called when the agent is resumed from suspension.

onTerminate() · method

Optional lifecycle method called when the agent is about to be terminated.

Types

AgentInfo

Information about an agent instance.

class AgentInfo {
  id: string
  name: string
  status: string
}

id · string

The unique identifier of the agent instance.

name · string

The name of the agent class.

status · string

The current status of the agent instance.

Example Usage

Here’s a complete example of a simple counter agent:

Agent Implementation

import { Agent } from "@hypermode/modus-sdk-as"

export class CounterAgent extends Agent {
  get name(): string {
    return "Counter"
  }

  private count: i32 = 0

  getState(): string | null {
    return this.count.toString()
  }

  setState(data: string | null): void {
    if (data == null) {
      return
    }
    this.count = i32.parse(data)
  }

  onInitialize(): void {
    console.info("Counter agent started")
  }

  onReceiveMessage(name: string, data: string | null): string | null {
    if (name == "count") {
      return this.count.toString()
    }

    if (name == "increment") {
      if (data != null) {
        this.count += i32.parse(data)
      } else {
        this.count++
      }
      return this.count.toString()
    }

    return null
  }
}

Function Integration

import { agents, AgentInfo } from "@hypermode/modus-sdk-as"
import { CounterAgent } from "./counterAgent"

// Register the agent
agents.register<CounterAgent>()

export function startCounterAgent(): AgentInfo {
  return agents.start("Counter")
}

export function getCount(agentId: string): i32 {
  const count = agents.sendMessage(agentId, "count")
  if (count == null) {
    return 0
  }
  return i32.parse(count)
}

export function updateCount(agentId: string): i32 {
  const count = agents.sendMessage(agentId, "increment")
  if (count == null) {
    return 0
  }
  return i32.parse(count)
}

export function updateCountAsync(agentId: string, qty: i32): void {
  agents.sendMessageAsync(agentId, "increment", qty.toString())
}

GraphQL Usage

Once deployed, your agent functions become available via GraphQL:

# Start a new agent
mutation {
  startCounterAgent {
    id
    name
    status
  }
}

# Get the current count
query {
  getCount(agentId: "agent_abc123")
}

# Increment the count
mutation {
  updateCount(agentId: "agent_abc123")
}