Testujte agenty pomocí sady Microsoft Agent 365 SDK

Před nasazením otestujte svého agenta lokálně pomocí Agents Playground. Tento průvodce se zabývá nastavením vývojového prostředí, konfigurací autentizace a ověřováním funkčnosti vašeho agenta pomocí testovacího nástroje Agents Playground.

Jakmile váš agent funguje lokálně, postupujte podle vývojového cyklu Agent 365 a testujte ho v aplikacích Microsoft 365, jako jsou Teams, Word a Outlook.

Předpoklady

Dříve než začnete s testováním agenta, se ujistěte, že máte nainstalovány následující předpoklady:

Obecné požadavky

Požadavky podle programovacího jazyka

Konfigurace prostředí pro testování agentů

Tato sekce popisuje, jak nastavit proměnné prostředí, provést autentizaci vývojového prostředí a připravit agenta poháněného platformou Agent 365 k testování.

Nastavte si prostředí pro testování agentů podle tohoto sekvenčního postupu:

  1. Nakonfigurujte své prostředí – Vytvořte nebo aktualizujte konfigurační soubor prostředí.

  2. Konfigurace LLM – Získejte API klíče a nastavte OpenAI nebo Azure OpenAI.

  3. Konfigurujte autentizaci – nastavte agentickou autentizaci:

  4. Reference proměnných prostředí – Nastavení požadovaných proměnných prostředí:

    1. Proměnné ověřování
    2. Konfigurace koncového bodu MCP
    3. Proměnné pozorovatelnosti
    4. Konfigurace serveru aplikace agenta

Po dokončení těchto kroků můžete začít testovat agenta v Agents Playground.

Krok 1: Konfigurujte své prostředí

Nastavte konfigurační soubor:

cp .env.template .env

Poznámka

Konfigurační šablony s požadovanými poli najdete v ukázkách Microsoft Agent 365 SDK.

Krok 2: Konfigurace LLM

Nastavte konfiguraci OpenAI nebo Azure OpenAI pro lokální testování. Přidejte své API klíče a koncové body z požadavků do konfiguračního souboru spolu s parametry modelu.

Přidejte soubor .env:

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

Proměnné prostředí pro LLM v Pythonu

Proměnná Popis Povinný Příklad
OPENAI_API_KEY API klíč pro službu OpenAI Service Pro OpenAI sk-proj-...
AZURE_OPENAI_API_KEY API klíč pro Azure OpenAI Service Pro Azure OpenAI a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT URL koncového bodu služby Azure OpenAI Service Pro Azure OpenAI https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Název nasazení v Azure OpenAI Pro Azure OpenAI gpt-4
AZURE_OPENAI_API_VERSION Verze API pro Azure OpenAI Pro Azure OpenAI 2024-02-15-preview

Krok 3: Konfigurace ověřování pro agenta

Zvolte jednu z následujících metod autentizace pro svého agenta:

  • Agentická autentizace – Použijte pro produkční scénáře, když je k dispozici agentická uživatelská identita.
  • OBO autentizace – Použijte pro produkční scénáře, když potřebujete delegovaná uživatelská oprávnění bez agentické uživatelské identity.
  • Autentizace pomocí nosného tokenu – používejte pouze pro rané vývojové a testovací scénáře před konfigurací produkční autentizace.

Agentická autentizace

Otevřete a365.generated.config.json ve svém pracovním adresáři a získáte údaje podrobného plánu agenta. Zkopírujte následující hodnoty:

Hodnota Popis
agentBlueprintId ID klienta agenta
agentBlueprintClientSecret Klientský tajný klíč vašeho agenta
tenantId ID klienta Microsoft Entra

Použijte tyto hodnoty k nastavení agentického ověřování ve vašem agentovi:

Přidejte následující nastavení do svého souboru .env, přičemž zástupné hodnoty nahraďte vašimi přihlašovacími údaji:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
Proměnná Popis Povinný Příklad
USE_AGENTIC_AUTH Povolit režim agentického ověřování Ano true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID ID klienta podrobného popisu agenta z a365.generated.config.json Ano 11112222-bbbb-3333-cccc-4444dddd5555
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Tajný klíč klienta podrobného popisu agenta z a365.generated.config.json Ano abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID ID klienta Microsoft Entra z a365.generated.config.json Ano 22223333-cccc-4444-dddd-5555eeee6666

Ověřování OBO

Použitím autentizace On-Behalf-Of (OBO) může váš agent přistupovat k nástrojům MCP serveru pomocí delegovaných uživatelských oprávnění, aniž by potřeboval agentní uživatelskou identitu. V tomto procesu agent obdrží delegovaný token uživatele a vymění jej, aby mohl provádět akce jménem uživatele.

Autentizace OBO je vhodná pro produkční scénáře, kde:

  • Váš agent nemá identitu agenta uživatele.
  • Musíte přistupovat ke zdrojům s oprávněními specifickými pro uživatele.
  • Chcete, aby agent jednal jménem ověřeného uživatele.

Další informace o tom, jak funguje tok OBO, naleznete v sekci Autentizační toky. Pro kompletní příklad implementace viz ukázka autorizace OBO v Sadě SDK pro agenty Microsoft 365.

Ověřování nosného tokenu

Pokud není produkční autentizace nakonfigurována, použijte pro rané vývojové a testovací scénáře autentizaci pomocí nosného tokenu k otestování svého agenta. Tato metoda používá interaktivní ověřování v prohlížeči k získání delegovaného přístupového tokenu. Použitím tohoto tokenu může váš agent volat nástroje MCP Server s vašimi uživatelskými oprávněními. Tento přístup simuluje, jak agent jako uživatel přistupuje ke zdrojům v produkčním prostředí, aniž by byla vyžadována skutečná instance agenta.

Nejprve použijte a365 develop add-permissions k přidání potřebných oprávnění MCP serveru do vaší aplikace:

a365 develop add-permissions

Poté použijte a365 develop get-token k získání a konfiguraci tokenů typu bearer:

a365 develop get-token

Příkaz get-token provádí automaticky:

  • Čte ToolingManifest.json pro zjištění všech nakonfigurovaných MCP serverů.
  • Získá jeden token pro každé publikum – servery MCP obdrží token s rozsahem pro jejich specifické ID aplikace; sdílené servery ATG obdrží token s rozsahem pro sdílené ID aplikace Agent Tools Gateway (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1).
  • Zapisuje tokeny do konfiguračních souborů vašeho projektu:
    • Tokeny pro jednotlivé servery: BEARER_TOKEN_<SERVER_NAME> (například BEARER_TOKEN_MCP_MAILTOOLS)
    • Sdílený ATG token: BEARER_TOKEN

Před spuštěním get-token přidejte zástupné položky do konfiguračního souboru projektu:

  • .NET: Přidejte "BEARER_TOKEN": "" a/nebo "BEARER_TOKEN_<SERVER_NAME>": "" do environmentVariables v každém profilu v Properties/launchSettings.json. Příkaz aktualizuje pouze profily, které již mají tyto klíče definované.
  • Python/Node.js: Vytvořte .env soubor s a BEARER_TOKEN= /nebo BEARER_TOKEN_<SERVER_NAME>= před spuštěním. Pokud soubor chybí, příkaz přeskočí ukládání a zobrazí pokyny.

Poznámka

Pokud spustíte a365 develop get-token --app-id <id> bez souboru a365.config.json, tokeny se automaticky neukládají. Zkopírujte a vložte je ručně do souboru Properties/launchSettings.json (pro .NET) nebo do souboru .env (pro Python/Node.js).

Nosné tokeny vyprší přibližně po jedné hodině. Použijte a365 develop get-token k obnovení tokenů, jejichž platnost vypršela.

Krok 4: Reference proměnných prostředí

Dokončete nastavení prostředí konfigurací následujících požadovaných proměnných prostředí:

Proměnné ověřování

Nastavte parametry obslužného modulu autentizace potřebné pro správnou funkci agentické autentizace.

Přidejte soubor .env:

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION
Proměnná Popis Povinný
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Typ obslužného modulu autentizace Ano
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Autentizační rozsahy pro Microsoft Graph Ano
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Alternativní název spojení podrobného plánu Ano
CONNECTIONSMAP_0_SERVICEURL Vzor URL služby pro mapování spojení Ano
CONNECTIONSMAP_0_CONNECTION Název spojení pro mapování Ano

Proměnné nosného tokenu (pouze pro lokální vývoj)

Proměnná Popis Povinný
BEARER_TOKEN Sdílený nosný token pro sdílené ATG MCP servery. Příkaz a365 develop get-token automaticky zapíše tento token. Pro lokální vývoj sdíleného ATG
BEARER_TOKEN_<SERVER_NAME> Nosný token pro jednotlivý server. SDK odvozuje název převedením mcpServerName z ToolingManifest.json na velká písmena, například mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS. Příkaz a365 develop get-token automaticky zapíše tento token. Na úrovni jednotlivého serveru pro lokální vývoj
SKIP_TOOLING_ON_ERRORS Nastavte na true pro přepnutí na čistý LLM, pokud se MCP nástroje nepodaří načíst. Platí pouze, pokud ASPNETCORE_ENVIRONMENT nebo ENVIRONMENT je Development. Ne

Důležité

Nosné tokeny jsou určeny pouze pro lokální vývoj. Nikdy nenastavujte ani BEARER_TOKEN ani BEARER_TOKEN_<SERVER_NAME> v produkčním nasazení.

Konfigurace koncového bodu MCP

Specifikujte koncový bod platformy Agent 365, ke kterému se váš agent připojuje. Když generujete manifest nástrojů, který definuje nástrojové servery pro vašeho agenta, určete koncový bod platformy MCP. Tento koncový bod určuje, ke kterému prostředí (předprodukci, testování nebo produkci) se MCP nástrojové servery připojují pro integrační možnosti Microsoft 365.

Přidejte soubor .env:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Proměnná Popis Požaduje se Výchozí Příklad
MCP_PLATFORM_ENDPOINT URL koncového bodu platformy MCP (preprod, test nebo prod) Ne Produkční koncový bod

Důležité: Pokud nespecifikujete MCP_PLATFORM_ENDPOINT, aplikace používá produkční koncový bod.

Poznámka

Pokud používáte simulovat server nástrojů z CLI, nastavte koncový bod na http://localhost:<port> podle čísla portu, které jste použili. Výchozí port je 5309.

Proměnné pozorovatelnosti

Nakonfigurujte tyto povinné proměnné pro umožnění protokolování a distribuovaného trasování vašeho agenta. Pro úplný seznam proměnných prostředí, konfiguračních možností a příkladů kódu viz Pozorovatelnost agenta.

Poznámka

Konfigurace pozorovatelnosti je stejná ve všech jazycích. Další informace viz Konfigurace.

Proměnná Popis Výchozí Příklad
ENABLE_A365_OBSERVABILITY_EXPORTER Export tras do služby pozorovatelnosti. Když je false, místo toho se exportují úseky do konzole. false true
A365_OBSERVABILITY_LOG_LEVEL Interní úroveň protokolování pro SDK pozorovatelnosti Užitečné při ladění problémů s exportem během testování. none info, warn, error, debug

Konfigurace serveru aplikace agenta

Konfigurujte port, na kterém běží server aplikačního agenta. Toto nastavení je volitelné a platí pro agenty implementované v Pythonu a JavaScriptu.

Přidejte soubor .env:

# Server Configuration
PORT=3978
Proměnná Popis Požaduje se Výchozí Příklad
PORT Číslo portu, na kterém běží server agenta Ne 3978 3978

Nainstalujte závislosti a spusťte aplikační server agenta

Po konfiguraci prostředí nainstalujte potřebné závislosti a spusťte server aplikace agenta lokálně pro testování.

Nainstalujte závislosti

uv pip install -e .

Tento příkaz načte závislosti balíčků definované v pyproject.toml a nainstaluje je z PyPI. Při vytváření agentní aplikace od nuly vytvořte soubor pyproject.toml pro definování vašich závislostí. Ukázkové agenty z úložiště vzorků již mají tyto balíčky definované. Můžete je podle potřeby přidávat nebo aktualizovat.

Spusťte server aplikace agenta

python <main.py>

Nahraďte <main.py> názvem vašeho hlavního Python souboru, který obsahuje vstupní bod pro vaši agentní aplikaci (například start_with_generic_host.py, app.py nebo main.py).

Nebo použijte uv:

uv run python <main.py>

Váš agent server je nyní spuštěný a připravený přijímat požadavky z nástroje Agents Playground nebo aplikací Microsoft 365.

Testování agenta v testovacím prostředí pro agenty

Agents Playground je lokální testovací nástroj, který simuluje prostředí Microsoft 365 bez potřeby plného nastavení tenantu. Je to nejrychlejší způsob, jak ověřit logiku a volání nástrojů vašeho agenta. Pro více informací viz Testování pomocí Agents Playground.

Konfigurace Agents Playground pro agentickou autentizaci

Poznámka

Tato konfigurace je potřebná pouze při použití agentické autentizace. Pokud používáte autentizaci pomocí nosného tokenu, můžete tuto část přeskočit a pokračovat přímo k Základnímu testu.

Když používáte agentickou autentizaci, nakonfigurujte soubor YAML pro Agents Playground s detaily vašeho agenta:

  1. Nastavte konfigurační soubor: Vytvořte nebo aktualizujte soubor .m365agentsplayground.yml ve složce, kde spouštíte Agents Playground. Podrobné pokyny k nastavení najdete v sekci Přizpůsobení kontextu Teams.

  2. Aktualizujte konfiguraci robota: Přidejte následující údaje o robotovi do souboru .m365agentsplayground.yml, přičemž nahraďte zástupné hodnoty skutečnými údaji vašeho agenta.

    bot:
  id: <your-agent-email>@<your-tenant>.onmicrosoft.com
  name: <Your Agent Name>
  role: agenticUser
  agenticUserId: <your-agentic-user-id>
  agenticAppId: <your-agentic-app-id>
    Vlastnost Popis Povinný
    id E-mailová adresa uživatele agenta ve formátu agentusername@tenant.onmicrosoft.com Ano
    name Zobrazované jméno pro vašeho agenta Ano
    role Musí být nastaveno na agenticUser pro agentickou autentizaci. Ano
    agenticUserId ID objektu uživatele agenta. Tuto hodnotu najdete v Centru pro správu Microsoft Entra na profilové stránce agenta. Ano
    agenticAppId ID agenta uživatele agenta. Tuto hodnotu najdete v Centru pro správu Microsoft Entra na profilové stránce agenta. Ano

Otevřete nový terminál (PowerShell na Windows) a spusťte Agents Playground:

agentsplayground

Tento příkaz otevře webový prohlížeč s rozhraním Agents Playground. Nástroj zobrazuje chatovací rozhraní, kde můžete posílat zprávy svému agentovi.

Základní test

Nejprve ověřte, že je váš agent správně nastavený. Pošlete zprávu agentovi:

What can you do?

Agent odpovídá podle instrukcí, které má nastavené na základě systémové výzvy a schopností vašeho agenta. Tato odpověď potvrzuje, že:

  • Váš agent funguje správně.
  • Agent může zpracovávat zprávy a odpovídat.
  • Komunikace mezi Agents Playground a vaším agentem funguje.

Testování volání nástrojů

Po nakonfigurování vašich MCP serverů nástrojů v toolingManifest.json (návod k nastavení viz Nástroje), otestujte volání nástrojů pomocí těchto příkladů:

Nejprve ověřte, které nástroje jsou k dispozici:

List all tools I have access to

Poté otestujte konkrétní volání nástrojů:

E-mailové nástroje

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

Očekávaná odpověď: Agent odešle e-mail pomocí serveru Mail MCP a potvrdí, že zpráva byla odeslána.

Kalendářové nástroje

List my calendar events for today

Očekávaná odpověď: Agent získá a zobrazí vaše kalendářní události pro aktuální den.

SharePoint nástroje

List all SharePoint sites I have access to

Očekávaná odpověď: Agent provede dotaz na SharePoint a vrátí seznam stránek, ke kterým máte přístup.

Volání nástrojů si můžete prohlédnout v:

  • Chatovací okno – zobrazit odpověď agenta a případné volání nástrojů.
  • Panel protokolů – viz podrobné informace o aktivitách včetně parametrů nástrojů a odpovědí.

Testování s aktivitami oznámení

Během lokálního vývoje testujte scénáře oznámení pomocí vestavěných spouštěčů oznámení v Agents Playground.

Snímek obrazovky ukazuje rozhraní Agents Playground s rozbalenou nabídkou Simulace aktivity, která zobrazuje možnosti Aktivace aktivity oznámení včetně Odeslat e-mail a Zmínit ve Wordu.

Než začnete testovat oznámení, ujistěte se, že:

Testování e-mailových oznámení

Pro testování zpracování e-mailových upozornění:

  1. Spusťte svého agenta a aplikaci Agents Playground.
  2. V Agents Playground přejděte na Simulace aktivity>Aktivace aktivity oznámení.
  3. Vyberte Odeslat e-mail.
  4. V dialogu pro zadání dat aktualizujte údaje testovacího e-mailu, například jméno odesílatele a obsah těla e-mailu podle potřeby.
  5. Vyberte možnost Odeslat aktivitu.
  6. Zobrazte výsledek jak v chatu, tak v panelu záznamů.

Agent obdrží simulované oznámení e-mailem a zpracuje ho podle vaší logiky zpracování oznámení. Podrobnosti o struktuře payloadu e-mailového oznámení najdete v části Datová část e-mailového oznámení.

Testování oznámení o zmínkách ve Wordu

Pro testování oznámení o zmínkách v dokumentu Word:

  1. Spusťte svého agenta a aplikaci Agents Playground.
  2. V Agents Playground přejděte na Simulace aktivity>Aktivace aktivity oznámení.
  3. Vyberte Zmínka ve Wordu.
  4. V dialogovém okně datové části aktualizujte údaje simulovaného komentáře, například ID dokumentu a text komentáře podle potřeby.
  5. Vyberte možnost Odeslat aktivitu.
  6. Zobrazte výsledek jak v chatu, tak v panelu záznamů.

Agent přijímá simulované oznámení o zmínce ve Wordu a reaguje podle vaší logiky zpracování oznámení. Podrobnosti o struktuře payloadu oznámení komentáře ve Wordu najdete v tématu Datová část oznámení o komentáři k dokumentu.

Otestujte události instalace a odinstalace agenta

Když se Agents Playground připojí k vašemu agentovi, automaticky odešle aktivitu InstallationUpdate s akcí add. Pokud implementujete obslužnou funkci pro instalaci, uvítací zpráva vašeho agenta se objeví v chatu ihned po navázání spojení.

Pro ověření zpracování instalačních událostí:

  1. Spusťte server agenta.
  2. Otevřete Agents Playground. Testovací prostředí se připojí k vašemu agentovi a automaticky spustí událost instalace.
  3. Potvrďte, že se v chatovací konverzaci objeví uvítací zpráva.

Snímek obrazovky znázorňující rozhraní Agents Playground s uvítacím vzkazem agenta „Děkuji, že jste mě najali! Těším se, až vám budu moci pomáhat na vaší profesní cestě!“, který se automaticky zobrazí v chatové konverzaci a v panelu protokolu po spuštění události instalace.

Podrobnosti o implementaci obslužné rutiny naleznete v tématu Zpracování událostí instalace a odinstalace agenta.

Zobrazit protokoly pozorovatelnosti

Pro zobrazení protokolů pozorovatelnosti během lokálního vývoje instrumentujte svého agenta kódem pozorovatelnosti (viz Pozorovatelnost pro příklady kódu) a nastavte proměnné prostředí podle pokynů v Proměnné pozorovatelnosti. Podrobné pokyny k validaci a očekávanému výstupu logů najdete v části Validace v místním prostředí. Po nastavení se v konzoli zobrazí stopy v reálném čase, které ukazují:

  • Stopy invokace agenta
  • Podrobnosti spuštění nástroje
  • Volání inferenčních LLM
  • Vstupní a výstupní zprávy
  • Použití tokenů
  • Doby odezvy
  • Informace o chybě

Tyto protokoly vám pomáhají ladit problémy, pochopit chování agenta a optimalizovat výkon. Před publikováním použijte téma Ověření pro zveřejnění obchodu k ověření, že jsou přítomny všechny požadované atributy.

Další kroky

Po otestování agenta lokálně ho nasadíte do Azure a zveřejníte v Microsoft 365.

Pro testování vašeho agenta v aplikacích Microsoft 365, jako jsou Teams, Word a Outlook, viz Životní cyklus vývoje řešení Agent 365.

Řešení problému

Tato sekce poskytuje řešení běžných problémů, se kterými se můžete setkat při lokálním testování agenta.

Zpropitné

Průvodce odstraňováním problémů s řešením Agent 365 obsahuje doporučení k odstraňování problémů na vysoké úrovni, osvědčené postupy a odkazy na obsah o řešení problémů pro každou část životního cyklu vývoje Agent 365.

Problémy s připojením a prostředím

Tyto problémy se týkají síťové konektivity, konfliktů portů a problémů s nastavením prostředí, které brání vašemu agentovi správně komunikovat.

Problémy s připojením k Agents Playground

Příznak: Agents Playground se nemůže připojit k vašemu agentovi.

Řešení:

  • Ověřte, že server agenta je v provozu.
  • Zkontrolujte, zda se čísla portů shodují mezi vaším agentem a Agents Playground.
  • Ujistěte se, že žádná pravidla firewallu neblokují místní připojení.
  • Zkuste restartovat jak agenta, tak Agents Playground.

Zastaralá verze Agents Playground

Příznak: Neočekávané chyby nebo chybějící funkce v Agents Playground.

Řešení: Odinstalujte a znovu nainstalujte Agents Playground.

winget uninstall agentsplayground
winget install agentsplayground

Konflikty portu

Příznak: Chyba signalizuje, že port je již obsazen.

Řešení:

  • Zastavte všechny ostatní instance vašeho agenta.
  • Změňte port ve své konfiguraci.
  • Ukončete všechny procesy používající port.
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Nelze přidat DeveloperMCPServer

Příznak: Chyba při pokusu o přidání DeveloperMCPServer ve Visual Studio Code.

Řešení: Zavřete a znovu otevřete Visual Studio Code, a poté zkuste server znovu přidat.

Problémy s ověřováním a tokeny

Tyto problémy nastávají, když se váš agent nemůže správně ověřit svou identitu vůči službám Microsoft 365, nebo když autentizační údaje vyprší či jsou špatně nakonfigurované.

Příznaky:

  • Chyby 401 Neautorizováno
  • Zprávy o vypršení platnosti nosného tokenu
  • Chyby agentického ověřování

Hlavní příčina:

  • Tokeny vyprší přibližně po jedné hodině
  • Nesprávná konfigurace ověřování
  • Chybějící nebo neplatné přihlašovací údaje

Řešení:

  • Pro vypršení platnosti nosného tokenu

    Obnovte svůj token a aktualizujte proměnné prostředí.

    # Get a new token
a365 develop get-token

# Update your .env file with the new token

  • Pro chyby nosného tokenu na jednotlivých serverech

    Ověřte, že váš konfigurační soubor obsahuje zástupné položky pro každý server (BEARER_TOKEN_<SERVER_NAME>), poté znovu spusťte a365 develop get-token, abyste je doplnili. SDK generuje název proměnné tak, že převede mcpServerName v ToolingManifest.json na velká písmena a nahradí pomlčky podtržítky (například mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS).

  • Chyby při agentické autentizaci (Python)

    Zkontrolujte soubor .env:

    # Should be (with underscore):
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

# Not:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

  • Pro chybějící přihlašovací údaje

    Před testováním si ověřte, že jsou přítomny požadované přihlašovací údaje.

    Ujistěte se, že .env nebo appsettings.json obsahuje:

    • Klíče API a tajné kódy
    • ID tenanta
    • ID klienta
    • ID podrobného plánu (v případě použití agentického ověření)

    Ověření:

    Otestujte jednoduchý požadavek v Agents Playground. Měli byste obdržet odpověď bez chyb 401.

  • Problémy s nástroji a oznámeními

    Tyto problémy se týkají spouštění nástrojů, interakcí se serverem MCP a doručování oznámení.

E-mail nebyl přijat

Příznak: Agent uvádí, že e-mail byl odeslán, ale neobdržíte jej

Řešení:

  • Zkontrolujte složku Nevyžádaná pošta nebo Spam.
  • Doručení e-mailu může trvat několik minut. Počkejte až pět minut.
  • Ověřte, zda e-mailová adresa příjemce je správná.
  • Zkontrolujte protokoly agenta, zda během odesílání e-mailů nedošlo k chybám.

Odpovědi na komentáře ve Wordu nefungují

Známý problém: Služba oznámení momentálně nepodporuje přímé odpovědi na komentáře ve Wordu. Tato funkcionalita je ve vývoji.

Zprávy se k agentovi nedostávají

Příznak: Vaše aplikace agenta nepřijímá zprávy, které jsou agentovi v Teams zasílány.

Možné příčiny:

  • Vývojářský portál není nakonfigurován podle podrobného plánu agenta.
  • Problémy s Azure Web App (neúspěšné nasazení, aplikace neběží, chyby konfigurace).
  • Instance agenta není v Teams správně vytvořena.

Řešení:

  • Ověřte konfiguraci vývojářského portálu:

    Ujistěte se, že dokončíte konfiguraci podrobného plánu agenta ve Vývojářském portálu. Zjistěte, jak nakonfigurovat podrobný plán agenta ve Vývojářském portálu.

  • Zkontrolujte stav Azure Web App:

    Pokud nasadíte svého agenta do Azure, ověřte, že webová aplikace běží správně:

    1. Přejděte na Azure Portal.
    2. Přejděte k prostředku své webové aplikace.
    3. Zkontrolujte Přehled>Stav (stav by měl být „Běží“).
    4. Zkontrolujte Stream protokolu v části Monitorování pro chyby modulu runtime.
    5. Zkontrolujte protokoly Centra nasazení a ověřte, zda nasazení proběhlo úspěšně.
    6. Ověřte, že Konfigurace>nastavení aplikace obsahují všechny požadované proměnné prostředí.

  • Ověřte vytvoření instance agenta:

    Ujistěte se, že správně vytvoříte instanci agenta v Microsoft Teams:

    1. Otevře záznam typu Microsoft Teams.
    2. Přejděte do části Aplikace a vyhledejte svého agenta.
    3. Ověřte, že se agent objevuje ve výsledcích vyhledávání.
    4. Pokud agent není nalezen, ověřte, že je zveřejněn v Centru pro správu Microsoft 365 – Agenti.
    5. Vytvořte novou instanci výběrem možnosti Přidat u svého agenta.
    6. Podrobné pokyny naleznete v Nasazení agentů.

Řešení problémů s protokoly pozorovatelnosti

Pokud záznamy pozorovatelnosti vašeho agenta neodpovídají očekávaným výsledkům, podívejte se na Řešení problémů v průvodci pozorovatelností.

  • Last updated on