Doc Improvement][Agentic ToC][4665936]

msteams-platform/agents-in-teams/build/app-manifest-for-agents-outline.md

@@ -0,0 +1,123 @@
+---
+title: App manifest for AI-powered agents  
+description: Reference guide to the JSON manifest that defines skills, permissions, and runtime requirements for Microsoft Teams agents and Copilot plug-ins.  
+ms.localizationpriority: medium  
+ms.topic: reference  
+ms.date: 07/02/2025  
+---
+# App manifest for AI-powered agents  
+
+[Brief intro – ≤ 75 words about the role of the manifest, where it lives, and how it powers both Teams and Copilot surfaces.]
+
+## Manifest versions and $schema URLs  
+
+| Version | Use-case | $schema URL | Notes |
+|---------|----------|-------------|-------|
+| `v1.22` | AI agents & Copilot plug-ins (preview) | `https://developer.microsoft.com/json-schemas/teams/v1.22/MicrosoftTeams.schema.json` | Adds `copilotAgents`, `actions`, `elementRelationshipSet`. |
+| `v1.16–1.21` | Classic Teams apps |  | Still supported; agents require 1.22+. |
+
+## Minimum file structure  
+
+```json
+{
+  "$schema": ".../v1.22/MicrosoftTeams.schema.json",
+  "manifestVersion": "1.22",
+  "version": "1.0.0",
+  "id": "<GUID>",
+  "developer": { ... },
+  "name": { "short": "Contoso Agent" },
+  "description": { "short": "..." },
+  "icons": { "color": "color.png", "outline": "outline.png" },
+  "copilotAgents": { ... },
+  "permissions": [ ... ],
+  "validDomains": [ ... ]
+}
+```
+
+## Key manifest sections for agents  
+
+### `copilotAgents`  
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `declarativeAgents` | array | Optional | Plug-in style agents powered by OpenAPI + declarative prompts. |
+| `customEngineAgents` | array | Optional | Agents that run custom orchestration logic. |
+
+#### Declarative agent example  
+
+```json
+{
+  "copilotAgents": {
+    "declarativeAgents": [
+      {
+        "id": "salesInsights",
+        "fullName": "Contoso Sales Insights",
+        "description": "Answer questions about opportunities",
+        "actions": [ "listDeals", "getDeal" ],
+        "knowledgeSources": [ "https://contoso.com/kb/sales" ]
+      }
+    ]
+  }
+}
+```
+
+### `actions`  
+
+Defines function-calling surface for Copilot.  
+
+```json
+"actions": [
+  {
+    "id": "getDeal",
+    "parameters": [
+      { "name": "dealId", "type": "string", "description": "CRM opportunity ID" }
+    ],
+    "description": "Fetches a specific deal"
+  }
+]
+```
+
+### `elementRelationshipSet` *(cross-host runtime)*  
+
+- `oneWayDependency` – e.g., message extension depends on bot.  
+- `mutualDependencies` – e.g., tab & agent must deploy together.  
+
+### `authorization.permissions.resourceSpecific`  
+
+Explain how to request RSC scopes so Copilot can call the agent on behalf of the user.
+
+### `webApplicationInfo`  
+
+Reference to Microsoft Entra app; required for SSO and Graph calls.
+
+### `validDomains`  
+
+List all service endpoints—including dev tunnels—your agent will call.
+
+## Tooling tips  
+
+- **Agents Toolkit** auto-generates and updates manifest during scaffold, debug, and deploy.  
+- **Developer Portal** offers a form-based manifest editor with agent-specific fields.  
+- Use `atk package` or `atk preview` to validate against the schema and perform static checks.
+
+## Common validation errors  
+
+| Error message | Fix |
+|---------------|-----|
+| `manifestVersion must be 1.22` | Upgrade `$schema` and `manifestVersion`. |
+| `actions.parameters missing description` | Add `description` to every parameter. |
+| `id not unique` | Generate a new GUID for each agent. |
+
+## Samples  
+
+- **Declarative plug-in manifest:** `teams-samples/agents/declarative-plugin/manifest.json`  
+- **Custom engine agent manifest:** `teams-samples/agents/custom-engine/manifest.json`
+
+## Next step  
+
+Learn how to [Build bots, message extensions, tabs, and cards](build-bots-message-extensions-tabs-cards-outline.md) that implement the skills declared in your manifest.
+
+## See also  
+
+- [Tools & SDKs for building agents](tools-sdk-for-agents-outline.md)
+- [Resource-specific consent for agents](../../graph-api/rsc/resource-specific-consent.md)

msteams-platform/agents-in-teams/build/build-bots-message-extensions-tabs-cards-outline.md

@@ -0,0 +1,119 @@
+---
+title: Build bots, message extensions, tabs, and cards for your agent  
+description: Implement conversational logic, rich UI surfaces, and interaction patterns that bring your AI-powered agent to life in Microsoft Teams.  
+ms.localizationpriority: medium  
+ms.topic: how-to  
+ms.date: 07/02/2025  
+---
+# Build bots, message extensions, tabs, and cards  
+
+[Template instruction → One-sentence overview: “This guide shows how to wire up core Teams capabilities—bots, message extensions, tabs, and Adaptive Cards—around your agent’s AI logic.”]
+
+## Prerequisites  
+
+- Completed [Quick-start guide](../get-started/quick-start-build-your-first-agent-outline.md)
+- Agents Toolkit CLI or IDE extension installed  
+- Teams AI library configured in your project  
+
+## 1. Add conversational bot logic  
+
+### Scaffold a bot endpoint  
+
+```bash
+atk add bot --name HelpDeskBot
+```  
+
+[Template instruction → Explain generated folders and Bot Framework adapter integration.]  
+
+### Register handlers with Teams AI library  
+
+```ts
+app.message(/.*/, async (context, state) => {
+  const response = await planner.completePrompt(context);
+  await context.sendActivity(response);
+});
+```  
+
+[Template instruction → ≤ 100 words explanation.]
+
+### Enable SSO & user context  
+
+[Template instruction → One code block `authentication.getAuthToken` + explanation.]
+
+## 2. Expose actions through message extensions  
+
+### Define search & action commands in manifest  
+
+```json
+"composeExtensions": [{
+  "botId": "{{BOT_ID}}",
+  "commands": [{
+    "id": "createTicket",
+    "type": "action",
+    "title": "Create ticket",
+    "description": "Open help-desk ticket"
+  }]
+}]
+```  
+
+### Handle `invoke` in code  
+
+[Template instruction → JS/TS snippet that returns Adaptive Card dialog.]
+
+## 3. Surface information with tabs  
+
+### Add a personal tab  
+
+```bash
+atk add tab --name Dashboard --personal
+```  
+
+[Template instruction → Link to TeamsJS pages.tabs API for navigation.]  
+
+### Embed Live Share canvas (optional)  
+
+[Template instruction → bullet with link.]
+
+## 4. Craft engaging Adaptive Cards  
+
+### Basic answer card  
+
+```json
+{
+  "type": "AdaptiveCard",
+  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
+  "version": "1.6",
+  "body": [
+    { "type": "TextBlock", "text": "${answer}", "wrap": true }
+  ],
+  "actions": [
+    { "type": "Action.Execute", "title": "More", "verb": "followUp" }
+  ]
+}
+```  
+
+[Template instruction → Show how to bind `${answer}` from LLM output.]
+
+### Universal Actions for up-to-date views  
+
+[template instruction → 2–3 sentence explanation + link to UA guide.]
+
+## 5. Connect everything through the planner  
+
+[Template instruction → Describe calling bot functions from cards via `Action.Execute`, storing state, and triggering planner steps.]
+
+## Testing checklist  
+
+- Bot responds in chat and channel scopes  
+- Message extension dialog loads and returns card  
+- Tab renders in Teams, Outlook, Microsoft 365 hub  
+- Card buttons invoke `adaptiveCard/action` successfully  
+
+## Next step  
+
+Move on to [Local testing your agent](../test/local-testing-your-agent-outline.md) to validate these capabilities end-to-end.
+
+## See also  
+
+- [Tools & SDKs for building agents](tools-sdk-for-agents-outline.md)
+- [Design best practices for agents](../plan/design-best-practices-for-agents-outline.md)

msteams-platform/agents-in-teams/build/tools-sdk-for-agents-outline.md

@@ -0,0 +1,83 @@
+---
+title: Tools and SDKs for building AI-powered agents  
+description: Set up your environment with the Microsoft 365 Agents Toolkit, Teams AI Library, TeamsJS, and other SDKs used to create, debug, and deploy agents.  
+ms.localizationpriority: medium  
+ms.topic: conceptual
+ms.date: 07/02/2025  
+---
+# Tools & SDKs for building agents  
+
+[Intro – ≤ 100 words explaining that you can start coding an agent in minutes using first-party tooling and familiar languages like JavaScript, TypeScript, .NET, or Python.]
+
+## Microsoft 365 Agents Toolkit  
+
+### Visual Studio Code extension  
+
+- New-project scaffolding (agent, bot, tab, message extension).  
+- One-click **Debug in Teams** with auto tunnel & manifest update.  
+- Built-in **Agents Playground** for local Copilot testing.  
+
+### Command-line interface (ATK CLI)  
+
+```bash
+npm install -g @microsoft/atk
+atk new
+atk provision && atk deploy
+```  
+
+- Works in CI/CD and non-VS Code environments.  
+
+### Visual Studio integration  
+
+- .NET templates (C#)  
+- CodeLens for provision / deploy / debug  
+
+## Teams AI Library  
+
+| Feature | Why it matters | Package |  
+|---------|----------------|---------|  
+| Planner & function calling | Map user intent to skills | `@microsoft/teams-ai` |  
+| Memory & state management | Multi-turn context | Same |  
+| Adaptive Card helpers | Build Universal Actions | Same |
+
+## Microsoft Teams JavaScript SDK (TeamsJS)  
+
+- Surface web content in Teams, Outlook, Microsoft 365.  
+- Namespaces: `app`, `pages.tabs`, `dialog`, `teamsCore`, etc.  
+- Tree-shakable imports for smaller bundles.  
+
+## Microsoft Graph SDK  
+
+- Access calendar, chat, files, people via agent skills.  
+- Works with Teams SSO and OBO flows.  
+- Language options: JS/TS, .NET, Python, Java.
+
+## Programming languages & runtimes  
+
+| Language | Toolkit template | Supported SDKs |  
+|----------|------------------|----------------|  
+| TypeScript / Node 18+ | ✔ | Agents Toolkit, Teams AI, TeamsJS, Graph |  
+| .NET 8 | ✔ | Teams AI (.NET), Graph SDK |  
+| Python 3.10+ | Preview | Teams AI (Python), Graph SDK |
+
+## Supporting services  
+
+- **Azure OpenAI / OpenAI** – LLM back-end for reasoning.  
+- **Azure Functions** – Lightweight APIs or background tasks.  
+- **Azure Fluid Relay / Live Share** – Real-time collaboration data.  
+
+## Sample repos  
+
+- `teams-samples/js/hello-agent` – Minimal custom engine agent.  
+- `teams-samples/csharp/sales-coach-agent` – Multi-skill enterprise sample.  
+- `teams-samples/python/rag-agent` – Retrieval-augmented generation demo.  
+
+## Next step  
+
+Go to [App manifest for agents](app-manifest-for-agents-outline.md) to learn how to declare your agent’s skills and permissions.
+
+## See also  
+
+- [Quick-start: build your first agent](../get-started/quick-start-build-your-first-agent-outline.md)  
+- [Teams AI Library reference](https://aka.ms/teams-ai-lib)  
+- [Agents Toolkit CLI reference](../../toolkit/Microsoft-365-Agents-Toolkit-CLI.md)

msteams-platform/agents-in-teams/classic/build-a-traditional-teams-app-outline.md

@@ -0,0 +1,54 @@
+---
+title: Build a traditional Microsoft Teams app  
+description: Learn the core surfaces—tabs, bots, message extensions, webhooks, and connectors—used to create classic Teams apps that don’t integrate with Copilot or the new agent runtime.  
+ms.localizationpriority: medium  
+ms.topic: conceptual
+ms.date: 07/02/2025  
+---
+# Build a traditional Microsoft Teams app  
+
+[Template instruction → Introduce in 3-4 sentences (< 100 words) what a **classic** Teams app is, why it’s still supported, and when you might choose it over an AI-powered agent.]
+
+## Why build a classic app  
+
+[Template instruction → Provide 2–3 bullets focusing on scenarios such as highly customized UI, legacy tenant environments, or meeting-stage media that isn’t yet agent-enabled.]
+
+## Core extensibility pillars  
+
+[Template instruction → List each pillar with one-line description.]  
+
+- Tabs (personal, channel, meeting)  
+- Bots (conversational experiences via Bot Framework)  
+- Message extensions (search & action commands)  
+- Webhooks and connectors (incoming/outgoing notifications)  
+- Meeting apps (side panel, stage, Live Share)  
+
+## Architecture snapshot  
+
+[Template instruction → Include simple diagram placeholder + 3-5 callouts showing Teams client, service-hosted web content, Bot Framework endpoint, and optional Azure Functions.]
+
+## Development lifecycle at a glance  
+
+1. Plan UX & capabilities  
+2. Scaffold project with **Teams Toolkit** (classic mode)  
+3. Test locally with dev tunnels  
+4. Validate manifest (`manifestVersion` ≤ 1.21)  
+5. Publish to Tenant or Teams Store  
+[Template instruction → Add one short sentence under each bullet.]
+
+## Relationship to AI-powered agents  
+
+[Template instruction → Explain in ≤ 70 words that classic apps can coexist with agents; you can migrate later by adding a `copilotAgents` block or keep both models side-by-side.]
+
+## Limitations  
+
+[Template instruction → Note that classic apps won’t appear in Copilot skill list and cross-host runtime may require additional manifest work.]
+
+## Next step  
+
+See [Tabs, bots & message extensions](tabs-bots-message-extensions-outline.md) for hands-on guides to each classic capability.
+
+## See also  
+
+- [Overview of the Teams developer platform](../overview/overview-of-teams-developer-platform-outline.md)  
+- [App manifest schema (v1.21)](../reference/sdk-and-api-reference-hub-outline.md)