Edit

Share via

Quickstart

Get started with Teams SDK quickly using the Teams CLI.

Set up a new project

Prerequisites

Note

UV is a fast Python package installer and resolver. While you can use other package managers like pip, UV provides better performance and dependency resolution for Teams SDK projects.

  • Node.js v.20 or higher. Install or upgrade from nodejs.org.

Instructions

Use the Teams CLI

Use your terminal to run the Teams CLI using npx:

npx @microsoft/teams.cli --version

Note

_The Teams CLI is a command-line tool that helps you create and manage Teams applications. It provides a set of commands to simplify the development process.

Using npx allows you to run the Teams CLI without installing it globally. You can verify it works by running the version command above.

Creating Your First Agent

Let's begin by creating a simple echo agent that responds to messages. Run:

npx @microsoft/teams.cli@latest new csharp quote-agent --template echo

npx @microsoft/teams.cli@latest new python quote-agent --template echo

npx @microsoft/teams.cli@latest new typescript quote-agent --template echo

This command:

  1. Creates a new directory called Quote.Agent.
  2. Bootstraps the echo agent template files into your project directory.
  3. Creates your agent's manifest files, including a manifest.json file and placeholder icons in the Quote.Agent/appPackage directory. The Teams app manifest is required for sideloading the app into Teams.
  1. Creates a new directory called quote-agent.
  2. Bootstraps the echo agent template files into it under quote-agent/src.
  3. Creates your agent's manifest files, including a manifest.json file and placeholder icons in the quote-agent/appPackage directory. The Teams app manifest is required for sideloading the app into Teams.

The echo template creates a basic agent that repeats back any message it receives - perfect for learning the fundamentals.

Running your agent

  1. Navigate to your new agent's directory:
cd Quote.Agent/Quote.Agent
  1. Install the dependencies:
dotnet restore
  1. Start the development server:
dotnet run

Navigate to your new agent's directory:

cd quote-agent

Start the development server:

uv run src\main.py
  1. Navigate to your new agent's directory:
cd quote-agent
  1. Install the dependencies:
npm install
  1. Start the development server:
npm run dev
  1. In the console, you should see a similar output:
[INFO] Microsoft.Hosting.Lifetime Now listening on: http://localhost:3978
[WARN] Echo.Microsoft.Teams.Plugins.AspNetCore.DevTools ⚠️  Devtools are not secure and should not be used production environments ⚠️
[INFO] Echo.Microsoft.Teams.Plugins.AspNetCore.DevTools Available at http://localhost:3979/devtools
[INFO] Microsoft.Hosting.Lifetime Application started. Press Ctrl+C to shut down.
[INFO] Microsoft.Hosting.Lifetime Hosting environment: Development

In the console, you should see a similar output:

[INFO] @teams/app Successfully initialized all plugins
[WARNING] @teams/app.DevToolsPlugin ⚠️ Devtools is not secure and should not be used in production environments ⚠️
[INFO] @teams/app.HttpPlugin Starting HTTP server on port 3978
INFO:     Started server process [6436]
INFO:     Waiting for application startup.
[INFO] @teams/app.DevToolsPlugin available at http://localhost:3979/devtools
[INFO] @teams/app.HttpPlugin listening on port 3978 🚀
[INFO] @teams/app Teams app started successfully
[INFO] @teams/app.DevToolsPlugin listening on port 3979 🚀
INFO:     Application startup complete..
INFO:     Uvicorn running on http://0.0.0.0:3979 (Press CTRL+C to quit)
  1. In the console, you should see a similar output:
> quote-agent@0.0.0 dev
> npx nodemon -w "./src/**" -e ts --exec "node -r ts-node/register -r dotenv/config ./src/index.ts"

[nodemon] 3.1.9
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): src/**
[nodemon] watching extensions: ts
[nodemon] starting `node -r ts-node/register -r dotenv/config ./src/index.ts`
[WARN] @teams/app/devtools ⚠️  Devtools are not secure and should not be used production environments ⚠️
[INFO] @teams/app/http listening on port 3978 🚀
[INFO] @teams/app/devtools available at http://localhost:3979/devtools

When the application starts, you'll see:

  1. An HTTP server starting up (on port 3978). This is the main server which handles incoming requests and serves the agent application.
  2. A devtools server starting up (on port 3979). This is a developer server that provides a web interface for debugging and testing your agent quickly, without having to deploy it to Teams.

Note

The DevTools server runs on a separate port to avoid conflicts with your main application server. This allows you to test your agent locally while keeping the main server available for Teams integration.

Now, navigate to the devtools server by opening your browser and navigating to http://localhost:3979/devtools. You should see a simple interface where you can interact with your agent. Try sending it a message!

alt-text for devtools-echo-chat.png

Next steps

After creating and running your first agent, read about the code basics to better understand its components and structure.

Otherwise, if you want to run your agent in Teams, you can check out the Running in Teams guide.

Resources

  • Last updated on