Migrating from Teams AI Library v1

# in main.py
import asyncio
import logging

from microsoft.teams.api import MessageActivity
from microsoft.teams.apps import ActivityContext, App, ErrorEvent
from microsoft.teams.common import LocalStorage

logger = logging.getLogger(__name__)

# Define the app
app = App()

# Optionally create local storage
storage: LocalStorage[str] = LocalStorage()

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    await ctx.send(f"You said '{ctx.activity.text}'")

# Listen for errors
@app.event("error")
async def handle_error(event: ErrorEvent) -> None:
    """Handle errors."""
    logger.error(f"Error occurred: {event.error}")
    if event.context:
        logger.warning(f"Context: {event.context}")


if __name__ == "__main__":
    asyncio.run(app.start())

# in api.py
from http import HTTPStatus

from aiohttp import web
from botbuilder.core.integration import aiohttp_error_middleware

from bot import app

routes = web.RouteTableDef()


@routes.post("/api/messages")
async def on_messages(req: web.Request) -> web.Response:
    res = await app.process(req)

    if res is not None:
        return res

    return web.Response(status=HTTPStatus.OK)


api = web.Application(middlewares=[aiohttp_error_middleware])
api.add_routes(routes)

# in app.py
from aiohttp import web

from api import api
from config import Config

if __name__ == "__main__":
    web.run_app(api, host="localhost", port=Config.PORT)

# in bot.py
import sys
import traceback

from botbuilder.core import TurnContext, MemoryStorage
from teams import Application, ApplicationOptions, TeamsAdapter
from teams.state import TurnState

from config import Config

config = Config()
storage = MemoryStorage()
app = Application[TurnState](
    ApplicationOptions(
        bot_app_id=config.APP_ID,
        adapter=TeamsAdapter(config),
        storage=storage
    )
)

@app.activity("message")
async def on_message(context: TurnContext, _state: TurnState):
    await context.send_activity(f"you said: {context.activity.text}")
    return True


@app.error
async def on_error(context: TurnContext, error: Exception):
    # This check writes out errors to console log .vs. app insights.
    # NOTE: In production environment, you should consider logging this to Azure
    #       application insights.
    print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
    traceback.print_exc()

    # Send a message to the user
    await context.send_activity("The bot encountered an error or bug.")

import { App } from '@microsoft/teams.apps';
import { LocalStorage } from '@microsoft/teams.common/storage';

// Define app
const app = new App({
  clientId: process.env.ENTRA_APP_CLIENT_ID!,
  clientSecret: process.env.ENTRA_APP_CLIENT_SECRET!,
  tenantId: process.env.ENTRA_TENANT_ID!,
});

// Optionally create local storage
const storage = new LocalStorage();

// Listen for errors
app.event('error', async (client) => {
  console.error('Error event received:', client.error);
  if (client.activity) {
    await app.send(
      client.activity.conversation.id,
      'An error occurred while processing your message.',
    );
  }
});

// App creates local server with route for /api/messages
// To reuse your restify or other server,
// create a custom `HttpPlugin`.
(async () => {
  // starts the server
  await app.start();
})();

import {
  ConfigurationServiceClientCredentialFactory,
  MemoryStorage,
  TurnContext,
} from 'botbuilder';
import { Application, TeamsAdapter } from '@microsoft/teams-ai';
import * as restify from 'restify';

// Create adapter.
const adapter = new TeamsAdapter(
    {},
    new ConfigurationServiceClientCredentialFactory({
        MicrosoftAppId: process.env.ENTRA_APP_CLIENT_ID,
        MicrosoftAppPassword: process.env.ENTRA_APP_CLIENT_SECRET,
        MicrosoftAppType: 'SingleTenant',
        MicrosoftAppTenantId: process.env.ENTRA_APP_TENANT_ID
    })
);

// Catch-all for errors.
const onTurnErrorHandler = async (context: TurnContext, error: any) => {
    console.error(`\n [onTurnError] unhandled error: ${error}`);
    // Send a message to the user
    await context.sendActivity('The bot encountered an error or bug.');
};

// Set the onTurnError for the singleton CloudAdapter.
adapter.onTurnError = onTurnErrorHandler;

// Create HTTP server.
const server = restify.createServer();
server.use(restify.plugins.bodyParser());

server.listen(process.env.port || process.env.PORT || 3978, () => {
    console.log(`\n${server.name} listening to ${server.url}`);
});

// Define storage and application
const app = new Application<ApplicationTurnState>({
    storage: new MemoryStorage()
});

// Listen for incoming server requests.
server.post('/api/messages', async (req, res) => {
    // Route received a request to adapter for processing
    await adapter.process(req, res, async (context) => {
        // Dispatch to application for routing
        await app.run(context);
    });
});

# Triggered when user sends "hi", "hello", or "greetings"
@app.on_message_pattern(re.compile(r"hello|hi|greetings"))
async def handle_greeting(ctx: ActivityContext[MessageActivity]) -> None:
    await ctx.reply("Hello! How can I assist you today?")

# Listens for ANY message received
@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    # Sends a typing indicator
    await ctx.reply(TypingActivityInput())
    await ctx.send(f"You said '{ctx.activity.text}'")

# Triggered when user sends "hi"
@app.message(re.compile(r"hi", re.IGNORECASE))
async def greeting(context: TurnContext, _state: AppTurnState) -> bool:
    await context.send_activity("Hi there!")
    return True

# Listens for ANY message received
@app.activity("message")
async def on_message(context: TurnContext, _state: TurnState):
    # Echoes back what user said
    await context.send_activity(f"you said: {context.activity.text}")
    return True

// triggers when user sends "/hi" or "@bot /hi"
app.message("/hi", async (context) => {
  await context.sendActivity("Hi!");
});
// listen for ANY message to be received
app.activity(
  ActivityTypes.Message,
  async (context) => {
    // echo back users request
    await context.sendActivity(
      `you said: ${context.activity.text}`
    );
  }
);

// triggers when user sends "/hi" or "@bot /hi"
app.message('/hi', async (client) => {
  // SDK does not auto send typing indicators
  await client.send({ type: 'typing' });
  await client.send("Hi!");
});
// listen for ANY message to be received
app.on('message', async (client) => {
  await client.send({ type: 'typing' });
  await client.send(
    `you said "${client.activity.text}"`
  );
});

@app.on_dialog_open
async def handle_dialog_open(ctx: ActivityContext[TaskFetchInvokeActivity]):
    data: Optional[Any] = ctx.activity.value.data
    dialog_type = data.get("opendialogtype") if data else None

    if dialog_type == "some_type":
         return InvokeResponse(
            body=TaskModuleResponse(
                task=TaskModuleContinueResponse(
                    value=UrlTaskModuleTaskInfo(
                        title="Dialog title",
                        height="medium",
                        width="medium",
                        url= f"https://${os.getenv("YOUR_WEBSITE_DOMAIN")}/some-path",
                        fallback_url= f"https://${os.getenv("YOUR_WEBSITE_DOMAIN")}/fallback-path-for-web",
                        completion_bot_id= os.getenv("ENTRA_APP_CLIENT_ID"),
                    )
                )
            )
        )

@app.on_dialog_submit
async def handle_dialog_submit(ctx: ActivityContext[TaskSubmitInvokeActivity]):
    data: Optional[Any] = ctx.activity.value.data
    dialog_type = data.get("submissiondialogtype") if data else None

    if dialog_type == "some_type":
        await ctx.send(json.dumps(ctx.activity.value))

    return TaskModuleResponse(task=TaskModuleMessageResponse(value="Received submit"))

@app.task_module.fetch("connect-account")
async def on_connect_account(context: TurnContext, _state: TurnState):
    return TaskModuleTaskInfo(
        title="Connect your Microsoft 365 account",
        height="medium",
        width="medium",
        url=f"https://{config.NEXT_PUBLIC_BOT_DOMAIN}/connections",
        fallbackUrl=f"https://{config.NEXT_PUBLIC_BOT_DOMAIN}/connections",
        completionBotId=config.NEXT_PUBLIC_BOT_ID,
    )

@app.task_modules.submit("connect-account")
async def on_submit_connect_account(context: TurnContext, _state: TurnState, data: Dict[str, Any]):
    print(json.dumps(data))
    await context.send_activity("You are all set! Now, how can I help you today?")
    return None

app.on('dialog.open', (client) => {
  const dialogType = client.activity.value.data?.opendialogtype;
  if (dialogType === 'some-type') {
    return {
      task: {
        type: 'continue',
        value: {
          title: 'Dialog title',
          height: 'medium',
          width: 'medium',
          url: `https://${process.env.YOUR_WEBSITE_DOMAIN}/some-path`,
          fallbackUrl: `https://${process.env.YOUR_WEBSITE_DOMAIN}/fallback-path-for-web`,
          completionBotId: process.env.ENTRA_APP_CLIENT_ID!,
        },
      },
    };
  }
});

app.on('dialog.submit', async (client) => {
  const dialogType = client.activity.value.data?.submissiondialogtype;
  if (dialogType === 'some-type') {
    const { data } = client.activity.value;
    await client.send(JSON.stringify(data));
  }
  return undefined;
});

app.taskModules.fetch('connect-account', async (context, state, data) => {
  const taskInfo: TaskModuleTaskInfo = {
    title: 'Connect your Microsoft 365 account',
    height: 'medium',
    width: 'medium',
    url: `https://${process.env.NEXT_PUBLIC_BOT_DOMAIN}/connections`,
    fallbackUrl: `https://${process.env.NEXT_PUBLIC_BOT_DOMAIN}/connections`,
    completionBotId: process.env.NEXT_PUBLIC_BOT_ID,
  };
  return taskInfo;
});
app.taskModules.submit('connect-account', async (context, state, data) => {
  console.log(
    `bot-app.ts taskModules.submit("connect-account"): data`,
    JSON.stringify(data, null, 4)
  );
  await context.sendActivity('You are all set! Now, how can I help you today?');
  return undefined;
});

Option 1

For existing cards like this, the simplest way to convert that to Teams SDK is this:

@app.on_message_pattern("/card")
async def handle_card_message(ctx: ActivityContext[MessageActivity]):
    print(f"[CARD] Card requested by: {ctx.activity.from_}")
    card = AdaptiveCard.model_validate(
        {
            "schema": "http://adaptivecards.io/schemas/adaptive-card.json",
            "version": "1.6",
            "type": "AdaptiveCard",
            "body": [
                {
                    "text": "Hello, world!",
                    "wrap": True,
                    "type": "TextBlock",
                },
            ],
            "msteams": {
                "width": "Full"
            }
        }
    )
    await ctx.send(card)

Option 2

For a more thorough port, you could also do the following:

@app.on_message_pattern("/card")
async def handle_card_message(ctx: ActivityContext[MessageActivity]):
    card = AdaptiveCard(
        schema="http://adaptivecards.io/schemas/adaptive-card.json",
        body=[
            TextBlock(text="Hello, world", wrap=True, weight="Bolder"),
        ],
        ms_teams=TeamsCardProperties(width='full'),
    )
    await ctx.send(card)

@app.message("/card")
async def adaptive_card(context: TurnContext, _state: AppTurnState) -> bool:
    attachment = CardFactory.adaptive_card(
         {
            "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
            "version": "1.6",
            "type": "AdaptiveCard",
            "body": [
                {
                    "text": "Hello, world!",
                    "wrap": True,
                    "type": "TextBlock",
                },
            ],
            "msteams": {
                "width": "Full"
            }
        }
    )
    await context.send_activity(Activity(attachments=[attachment]))
    return True

Option 1

For existing cards like this, the simplest way to convert that to Teams SDK is this:

app.message('/card', async (client) => {
  await client.send({
    $schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
    version: '1.5',
    type: 'AdaptiveCard',
    body: [
      {
        type: 'TextBlock',
        text: 'Hello, world!',
        wrap: true,
        isSubtle: false,
      },
    ],
    msteams: {
      width: 'Full',
    },
  });
});

Option 2

For a more thorough port, you could also do the following:

import { Card, TextBlock } from '@microsoft/teams.cards';

app.message('/card', async (client) => {
  await client.send(
    new Card(new TextBlock('Hello, world!', { wrap: true, isSubtle: false })).withOptions({
      width: 'Full',
    })
  );
});

app.message('/card', async (context: TurnContext) => {
  const card = CardFactory.adaptiveCard({
    $schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
    version: '1.5',
    type: 'AdaptiveCard',
    body: [
      {
        type: 'TextBlock',
        text: 'Hello, world!',
        wrap: true,
        isSubtle: false,
      },
    ],
    msteams: {
      width: 'Full',
    },
  });
  await context.sendActivity({
    attachments: [card],
  });
});

app = App()

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]):
    ctx.logger.info("User requested sign-in.")
    if ctx.is_signed_in:
        await ctx.send("You are already signed in.")
    else:
        await ctx.sign_in()

@app.on_message_pattern("/signout")
async def handle_sign_out(ctx: ActivityContext[MessageActivity]):
    await ctx.sign_out()
    await ctx.send("You have been signed out.")

@app.event("sign_in")
async def handle_sign_in(event: SignInEvent):
    """Handle sign-in events."""
    await event.activity_ctx.send("You are now signed in!")

@app.event("error")
async def handle_error(event: ErrorEvent):
    """Handle error events."""
    print(f"Error occurred: {event.error}")
    if event.context:
        print(f"Context: {event.context}")

app = Application[TurnState[ConversationState, UserState, TempState]](
    ApplicationOptions(
        bot_app_id=config.APP_ID,
        storage=MemoryStorage(),
        adapter=TeamsAdapter(config),
        auth=AuthOptions(
            default="graph",
            auto=True,
            settings={
                "graph": OAuthOptions(
                    connection_name=config.OAUTH_CONNECTION_NAME,
                    title="Sign In",
                    text="please sign in",
                    end_on_invalid_message=True,
                    enable_sso=True,
                ),
            },
        ),
    )
)

auth = app.auth.get("graph")

@app.message("/signout")
async def on_sign_out(
    context: TurnContext, state: TurnState[ConversationState, UserState, TempState]
):
    await auth.sign_out(context, state)
    await context.send_activity("you are now signed out...👋")
    return False

@auth.on_sign_in_success
async def on_sign_in_success(
    context: TurnContext, state: TurnState[ConversationState, UserState, TempState]
):
    await context.send_activity("successfully logged in!")
    await context.send_activity(f"token: {state.temp.auth_tokens['graph']}")

@auth.on_sign_in_failure
async def on_sign_in_failure(
    context: TurnContext,
    _state: TurnState[ConversationState, UserState, TempState],
    _res: SignInResponse,
):
    await context.send_activity("failed to login...")

const app = new App({
  oauth: {
    // oauth configurations
    /**
     * The name of the auth connection to use.
     * It should be the same as the OAuth connection name defined in the Azure Bot configuration.
     */
    defaultConnectionName: 'graph',
  },
  logger: new ConsoleLogger('@tests/auth', { level: 'debug' }),
});

app.message('/signout', async (client) => {
  if (!client.isSignedIn) return;
  await client.signout(); // call signout for your auth connection...
  await client.send('you have been signed out!');
});

app.message('/help', async (client) => {
  await client.send('your help text');
});

app.on('message', async (client) => {
  if (!client.isSignedIn) {
    await client.signin({
      // Customize the OAuth card text (only renders in OAuth flow, not SSO)
      oauthCardText: 'Sign in to your account',
      signInButtonText: 'Sign in',
    }); // call signin for your auth connection...
    return;
  }

  const me = await client.userGraph.me.get();
  log.info(`user "${me.displayName}" already signed in!`);
});

app.event('signin', async (client) => {
  const me = await client.userGraph.me.get();
  await client.send(`user "${me.displayName}" signed in.`);
  await client.send(`Token string length: ${client.token.token.length}`);
});

const storage = new MemoryStorage();
const app = new Application({
  storage: new MemoryStorage(),
  authentication: {
    autoSignIn: (context) => {
      const activity = context.activity;
      // No auth when user wants to sign in
      if (activity.text === '/signout') {
        return Promise.resolve(false);
      }
      // No auth for "/help"
      if (activity.text === '/help') {
        return Promise.resolve(false);
      }
      // Manually sign in (for illustrative purposes)
      if (activity.text === '/signin') {
        return Promise.resolve(false);
      }
      // For all other messages, require sign in
      return Promise.resolve(true);
    },
    settings: {
      graph: {
        connectionName: process.env.OAUTH_CONNECTION_NAME!,
        title: 'Sign in',
        text: 'Please sign in to use the bot.',
        endOnInvalidMessage: true,
        tokenExchangeUri: process.env.TOKEN_EXCHANGE_URI!,
        enableSso: true,
      },
    },
  },
});

app.message('/signout', async (context, state) => {
  await app.authentication.signOutUser(context, state);

  // Echo back users request
  await context.sendActivity(`You have signed out`);
});

app.message('/signin', async (context, state) => {
  let token = state.temp.authTokens['graph'];
  if (!token) {
    const res = await app.authentication.signInUser(context, state);
    if (res.error) {
      console.log(res.error);
      return;
    }
    token = state.temp.authTokens['graph'];
  }

  if (token) {
    // Echo back users request
    await context.sendActivity(`You are already authenticated!`);
    return;
  }

  // Sign in is pending...
});

app.message('/help', async (context, state) => {
  await context.sendActivity(`your help text`);
});

app.authentication.get('graph').onUserSignInSuccess(async (context, state) => {
  // Successfully logged in
  await context.sendActivity('Successfully logged in');
  await context.sendActivity(`Token string length: ${state.temp.authTokens['graph']!.length}`);
});

app.authentication.get('graph').onUserSignInFailure(async (context, _state, error) => {
  // Failed to login
  await context.sendActivity(`Failed to login with error: ${error.message}`);
});

In Teams SDK, there is no actions.json file. Instead, function prompts, parameters, etc. are declared in your code.

import '@azure/openai/types';
import { ChatPrompt, Message } from '@microsoft/teams.ai';
import { MessageActivity } from '@microsoft/teams.api';
import { App } from '@microsoft/teams.apps';
import { LocalStorage } from '@microsoft/teams.common/storage';
import { OpenAIChatModel } from '@microsoft/teams.openai';

interface IStorageState {
  status: boolean;
  messages: Message[];
}

const storage = new LocalStorage<IStorageState>();

const app = new App();

app.on('message', async (client) => {
  let state = storage.get(client.activity.from.id);

  if (!state) {
    state = {
      status: false,
      messages: [],
    };

    storage.set(client.activity.from.id, state);
  }

  const prompt = new ChatPrompt({
    messages: state.messages,
    instructions: `The following is a conversation with an AI assistant.
  The assistant can turn a light on or off.
  The lights are currently off.`,
    model: new OpenAIChatModel({
      model: 'gpt-4o-mini',
      apiKey: process.env.OPENAI_API_KEY,
    }),
  })
    .function('get_light_status', 'get the current light status', () => {
      return state.status;
    })
    .function('toggle_lights', 'toggles the lights on/off', () => {
      state.status = !state.status;
      storage.set(client.activity.from.id, state);
    })
    .function(
      'pause',
      'delays for a period of time',
      {
        type: 'object',
        properties: {
          time: {
            type: 'number',
            description: 'the amount of time to delay in milliseconds',
          },
        },
        required: ['time'],
      },
      async ({ time }: { time: number }) => {
        await new Promise((resolve) => setTimeout(resolve, time));
      }
    );

  await prompt.send(client.activity.text, {
    onChunk: (chunk) => {
      client.stream.emit(new MessageActivity(chunk));
    },
  });
});

(async () => {
  await app.start();
})();

// Create AI components
const model = new OpenAIModel({
  // OpenAI Support
  apiKey: process.env.OPENAI_KEY!,
  defaultModel: 'gpt-4o',

  // Azure OpenAI Support
  azureApiKey: process.env.AZURE_OPENAI_KEY!,
  azureDefaultDeployment: 'gpt-4o',
  azureEndpoint: process.env.AZURE_OPENAI_ENDPOINT!,
  azureApiVersion: '2023-03-15-preview',

  // Request logging
  logRequests: true,
});

const prompts = new PromptManager({
  promptsFolder: path.join(__dirname, '../src/prompts'),
});

// Define a prompt function for getting the current status of the lights
prompts.addFunction('getLightStatus', async (context, memory) => {
  return memory.getValue('conversation.lightsOn') ? 'on' : 'off';
});

const planner = new ActionPlanner({
  model,
  prompts,
  defaultPrompt: 'tools',
});

// Define storage and application
const storage = new MemoryStorage();
const app = new Application<ApplicationTurnState>({
  storage,
  ai: {
    planner,
  },
});

// Register action handlers
app.ai.action('ToggleLights', async (context, state) => {
  state.conversation.lightsOn = !state.conversation.lightsOn;
  const lightStatusText = state.conversation.lightsOn ? 'on' : 'off';
  await context.sendActivity(`[lights ${lightStatusText}]`);
  return `the lights are now ${lightStatusText}$`;
});

interface PauseParameters {
  time: number;
}

app.ai.action('Pause', async (context, state, parameters: PauseParameters) => {
  await context.sendActivity(`[pausing for ${parameters.time / 1000} seconds]`);
  await new Promise((resolve) => setTimeout(resolve, parameters.time));
  return `done pausing`;
});

// Listen for incoming server requests.
server.post('/api/messages', async (req, res) => {
  // Route received a request to adapter for processing
  await adapter.process(req, res as any, async (context) => {
    // Dispatch to application for routing
    await app.run(context);
  });
});

And the corresponding actions.json file:

[
  {
    "name": "ToggleLights",
    "description": "Turns on/off the lights"
  },
  {
    "name": "Pause",
    "description": "Delays for a period of time",
    "parameters": {
      "type": "object",
      "properties": {
        "time": {
          "type": "number",
          "description": "The amount of time to delay in milliseconds"
        }
      },
      "required": ["time"]
    }
  }
]

# Reply with message including feedback buttons
@app.on_message
async def handle_feedback(ctx: ActivityContext[MessageActivity]):
    await ctx.send(MessageActivityInput(text="Hey, give me feedback!").add_ai_generated().add_feedback())

@app.on_message_submit_feedback
async def handle_message_feedback(ctx: ActivityContext[MessageSubmitActionInvokeActivity]):
    # Custom logic here..

Note: In Teams SDK, you do not need to opt into feedback at the App level.

app = Application[AppTurnState](
    ApplicationOptions(
        # ... other options
        ai=AIOptions(
            enable_feedback_loop=enableFeedbackLoop
        ),
    )
)

@app.message()
async def on_message(context: TurnContext, state: AppTurnState):
    await context.send_activity(Activity(text="Hey, give me feedback!", channel_data={"feedbackLoop": { "type": "custom"}}))

@app.feedback_loop()
async def feedback_loop(context: TurnContext, state: AppTurnState, feedback_data: FeedbackLoopData):
    print("Feedback loop triggered")

import { MessageActivity } from '@microsoft/teams.api';

// Reply with message including feedback buttons
app.on('message', async (client) => {
  await client.send(
    new MessageActivity('Hey, give me feedback!')
      .addAiGenerated() // AI generated label
      .addFeedback() // Feedback buttons
  );
});

// Listen for feedback submissions
app.on('message.submit.feedback', async ({ activity, log }) => {
  // custom logic here...
});

Note: In Teams SDK, you do not need to opt into feedback at the App level.

export const app = new Application({
  ai: {
    // opts into feedback loop
    enable_feedback_loop: true,
  },
});

// Reply with message including feedback buttons
app.activity(ActivityTypes.Message, async (context) => {
  await context.sendActivity({
    type: ActivityTypes.Message,
    text: `Hey, give me feedback!`,
    channelData: {
      feedbackLoop: {
        type: 'custom',
      },
    },
  });
});

// Handle feedback submit
app.feedbackLoop(async (context, state, feedbackLoopData) => {
  // custom logic here...
});