Quickstart: Create an agent with the Agents SDK for JavaScript

This quickstart guides you through creating a custom engine agent that just replies with whatever you send to it.

Prerequisites

• Node.js v22 or newer

  • To install Node.js go to nodejs.org, and follow the instructions for your operating system.
  • To verify the version, in a terminal window type node --version.

• A code editor of your choice. These instructions use Visual Studio Code.

Initialize the project and install the SDK

Use npm to initialize a node.js project by creating a package.json and installing the required dependencies

1. Open a terminal and create a new folder

   mkdir echo
   cd echo
   

2. Initialize the node.js project

   npm init -y
   

3. Install the Agents SDK

   npm install @microsoft/agents-hosting-express
   

4. Open the folder using Visual Studio Code using the this command:

   code .
   

Import the required libraries

Create the file index.mjs and import the following NPM packages into your application code:

• @microsoft/agents-hosting
• @microsoft/agents-hosting-express

// index.mjs
import { startServer } from '@microsoft/agents-hosting-express'
import { AgentApplication, MemoryStorage } from '@microsoft/agents-hosting'

Implement the EchoAgent as an AgentApplication

In index.mjs, add the following code to create the EchoAgent extending the AgentApplication, and implement three routes to respond to three events:

• Conversation Update
• the message /help
• any other activity

class EchoAgent extends AgentApplication {
  constructor (storage) {
    super({ storage })

    this.onConversationUpdate('membersAdded', this._help)
    this.onMessage('/help', this._help)
    this.onActivity('message', this._echo)
  }

  _help = async context => 
    await context.sendActivity(`Welcome to the Echo Agent sample 🚀. 
      Type /help for help or send a message to see the echo feature in action.`)

  _echo = async (context, state) => {
    let counter= state.getValue('conversation.counter') || 0
    await context.sendActivity(`[${counter++}]You said: ${context.activity.text}`)
    state.setValue('conversation.counter', counter)
  }
}

Start the web server to listen in localhost:3978

At the end of index.mjs start the web server using startServer based on express using MemoryStorage as the turn state storage.

startServer(new EchoAgent(new MemoryStorage()))

Run the Agent locally in anonymous mode

From your terminal, run this command:

node index.mjs

The terminal should return this:

Server listening to port 3978 on sdk 0.6.18 for appId undefined debug undefined

Test the agent locally

1. From another terminal (to keep the agent running) install the Microsoft 365 Agents Playground with this command:

   npm install -D @microsoft/teams-app-test-tool
   

   The terminal should return something like:

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. Run the test tool to interact with your agent using this command:

   node_modules/.bin/teamsapptester
   

   The terminal should return something like:

   Telemetry: agents-playground-cli/serverStart {"cleanProperties":{"options":"{\"configFileOptions\":{\"path\":\"<REDACTED: user-file-path>\"},\"appConfig\":{},\"port\":56150,\"disableTelemetry\":false}"}}
   
   Telemetry: agents-playground-cli/cliStart {"cleanProperties":{"isExec":"false","argv":"<REDACTED: user-file-path>,<REDACTED: user-file-path>"}}
   
   Listening on 56150
   Microsoft 365 Agents Playground is being launched for you to debug the app: http://localhost:56150
   started web socket client
   started web socket client
   Waiting for connection of endpoint: http://127.0.0.1:3978/api/messages
   waiting for 1 resources: http://127.0.0.1:3978/api/messages
   wait-on(37568) complete
   Telemetry: agents-playground-server/getConfig {"cleanProperties":{"internalConfig":"{\"locale\":\"en-US\",\"localTimezone\":\"America/Los_Angeles\",\"channelId\":\"msteams\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"installationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"conversationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   

The teamsapptester command opens your default browser and connects to your agent.

Now you can send any message to see the echo reply, or send the message /help to see how that message is routed to the _help handler.

Next steps

Provision Azure Bot resources to use with Agents SDK