Microsoft Teams bots¶
A bot in Teams sits where your people work, and they'll paste anything into it. Send its model calls through the gateway and each answer is checked against your policies, charged to the right team and recorded in Request logs, and the bot can use Claude or Gemini as well as OpenAI's models.
What it is¶
A Teams bot (Microsoft now also calls them agents) is your own code, built with the Teams SDK (formerly the Teams AI
Library) or the older Bot Framework SDK, that receives messages from Teams and calls a model to answer. The gateway
carries that model call. Microsoft's current guidance for the Teams SDK is to call models with the openai package
directly, so the change is the same two settings as any OpenAI client.
Copilot in Teams uses models Microsoft runs; it doesn't go through the gateway. Agents built in Copilot Studio use the models Copilot Studio runs, not your bot's code, so this page doesn't apply to them. Its prompt tools can also use a model you deploy in Microsoft Foundry, connected by its Azure address but not another address, so those calls don't go through the gateway either.
The two settings¶
The two settings belong to the model client inside the bot:
| Setting | Environment variable | Value |
|---|---|---|
| Base address | OPENAI_BASE_URL |
https://<your-gateway>/v1 |
| Key | OPENAI_API_KEY |
Your Vidai key (starts vk_), never a provider's key |
Use the plain OpenAI client, not AzureOpenAI, even when the model behind it is on Azure: the AzureOpenAI client
sends its key in an api-key header, which the gateway doesn't accept, and builds Azure deployment addresses. The
gateway reaches your Azure OpenAI deployments itself.
Keep the key in your host's secret store, such as Azure Key Vault, not in the code. The gateway's address is under Connect your app on the Keys page and in System › Settings › Gateway. You get the key from Keys › Issue a key; its secret is shown once. A bot is a good fit for an agent's key: its calls then show under that agent.
A minimal call¶
import OpenAI from "openai";
import { App } from "@microsoft/teams.apps";
const llm = new OpenAI(); // reads OPENAI_BASE_URL and OPENAI_API_KEY
const app = new App();
app.on("message", async ({ reply, activity }) => {
await reply({ type: "typing" });
const answer = await llm.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: activity.text }],
});
await reply(answer.choices[0].message.content ?? "");
});
app.start();
import asyncio
from openai import AsyncOpenAI
from microsoft_teams.api import MessageActivity
from microsoft_teams.apps import ActivityContext, App
llm = AsyncOpenAI() # reads OPENAI_BASE_URL and OPENAI_API_KEY
app = App()
@app.on_message
async def answer(ctx: ActivityContext[MessageActivity]):
reply = await llm.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": ctx.activity.text}],
)
await ctx.send(reply.choices[0].message.content)
asyncio.run(app.start())
from botbuilder.core import ActivityHandler, TurnContext
from openai import AsyncOpenAI
llm = AsyncOpenAI() # reads OPENAI_BASE_URL and OPENAI_API_KEY
class VidaiBot(ActivityHandler):
async def on_message_activity(self, turn: TurnContext):
reply = await llm.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": turn.activity.text}],
)
await turn.send_activity(reply.choices[0].message.content)
The same code calls Claude or Gemini: put a name such as claude-sonnet-4.5 in model. The gateway translates the
request for that provider and the answer back into the OpenAI shape.
Streaming¶
The Teams SDK can stream an answer into a message as it arrives. Stream from the gateway as in OpenAI SDK for TypeScript and pass the text along; a stream from Claude or Gemini arrives as OpenAI chunks.
Tool calls¶
A bot that acts (books a room, opens a ticket) passes tools to the model and runs the ones it calls. Tools work on
every provider the gateway translates to, exactly as in OpenAI SDK for Python.
Tools that come from an MCP server are offered to the model the same way: see MCP. In Request
logs, the Tool filter under More filters finds the calls that offered or called a tool by its name.
Reading what the gateway did¶
const { data, response } = await llm.chat.completions
.create({ model: "gpt-4o-mini", messages })
.withResponse();
console.log(response.headers.get("x-vidai-request-id")); // paste into Request logs › Request reference
Cost is never in the answer: find the call in Request logs.
Errors¶
import OpenAI from "openai";
try {
await llm.chat.completions.create({ model: "gpt-4o-mini", messages });
} catch (e) {
if (e instanceof OpenAI.APIError) {
const code = e.headers?.["x-vidai-error-code"];
await reply(code === "content_guardrail_blocked"
? "I can't help with that message: it was stopped by your organisation's guardrails."
: "Something went wrong; please try again in a minute.");
}
}
Match on x-vidai-error-code, not on the message. The full list is in the
OpenAI SDK for Python page.
Model names¶
Use the names your organisation has approved, as listed under Models in the Control room, not Azure deployment
names. llm.models.list() returns exactly the models the bot's key may call.
What goes through the gateway¶
| In Teams | Through the gateway |
|---|---|
Model calls your bot makes with the openai client pointed at the gateway |
Yes, to every provider your organisation has set up |
A bot that calls Azure OpenAI with the AzureOpenAI client or its own key |
No: change it to the plain client and the gateway |
| Copilot in Teams | No: it uses models Microsoft runs |
Check it works in a minute¶
Start the bot (the Teams SDK's local playground or a test tenant) and send: "reply with exactly: ok". It should answer
ok. The call shows in Request logs within seconds.
Good to know¶
- One bot serving many tenants can use one key per tenant, so each one's spend is apart.
- The SDK retries twice by default; a fallback chain may already have tried another model first. Set
maxRetries: 0(TypeScript) ormax_retries=0(Python) if you don't want both. - The gateway's own 429 has no
Retry-Afterheader; back off on your side. - The bot's own sign-in to Teams (its app id and secret) has nothing to do with the gateway; only the model calls change.