Sdílet prostřednictvím

Testování agentů pomocí sady Microsoft Agent 365 SDK

Důležité

Abyste získali přednostní přístup k Microsoft Agentu 365, musíte být součástí programu Frontier Preview. Hranice vás spojuje přímo s nejnovějšími inovacemi umělé inteligence Microsoftu. Verze Preview hranice podléhají stávajícím podmínkám verze Preview vašich smluv se zákazníkem. Vzhledem k tomu, že tyto funkce jsou stále ve vývoji, jejich dostupnost a možnosti se můžou v průběhu času měnit.

Před nasazením otestujte agenta místně pomocí služby Agents Playground. Tato příručka popisuje nastavení vývojového prostředí, konfiguraci ověřování a ověřování funkcí agenta pomocí testovacího nástroje Agents Playground.

Jakmile agent pracuje místně, můžete ho nasadit a publikovat pro testování v aplikacích Microsoftu 365, jako je Teams.

Předpoklady

Dříve než začnete, se ujistěte, že splňujete následující předpoklady:

Běžné požadavky

Požadavky specifické pro jazyk

Konfigurace testovacího prostředí agenta

Tato část popisuje nastavení proměnných prostředí, ověřování vývojového prostředí a přípravu agenta 365 na testování.

Nastavení testovacího prostředí agenta se řídí sekvenčním pracovním postupem:

  1. Konfigurace prostředí – Vytvoření nebo aktualizace konfiguračního souboru prostředí

  2. Konfigurace LLM – Získání klíčů rozhraní API a konfigurace nastavení OpenAI nebo Azure OpenAI

  3. Konfigurace ověřování – Nastavení ověřování pomocí agenta

  4. Referenční informace o proměnných prostředí – Konfigurace 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 aplikačního serveru agenta

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

Krok 5: Konfigurujte své prostředí

Nastavte konfigurační soubor:

cp .env.template .env

Poznámka:

Projděte si ukázky sady Microsoft Agent 365 SDK a vyhledejte šablony konfigurace zobrazující požadovaná pole.

Krok 2: Konfigurace LLM

Nakonfigurujte nastavení OpenAI nebo Azure OpenAI pro místní testování. Přidejte klíče rozhraní API a koncové body služby získané z požadavků do konfiguračního souboru spolu s parametry modelu.

Přidejte do .env souboru:

# 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í PYTHON LLM

Proměnná Description Požadováno Příklad
OPENAI_API_KEY Klíč rozhraní API pro službu OpenAI Pro OpenAI sk-proj-...
AZURE_OPENAI_API_KEY Klíč rozhraní API pro službu Azure OpenAI Pro Azure OpenAI: Spusťte a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT Adresa URL koncového bodu služby Azure OpenAI Pro Azure OpenAI: Spusťte https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Název nasazení v Azure OpenAI Pro Azure OpenAI: Spusťte gpt-4
AZURE_OPENAI_API_VERSION Verze rozhraní API pro Azure OpenAI Pro Azure OpenAI: Spusťte 2024-02-15-preview

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

Pomocí příkazu A365 CLI a365 config display načtěte přihlašovací údaje podrobného plánu agenta.

a365 config display -g

Tento příkaz zobrazí konfiguraci podrobného plánu agenta. Nastavte následující hodnoty:

Hodnota Popis
agentBlueprintId ID klienta vašeho agenta
agentBlueprintClientSecret Tajný klíč klienta vašeho agenta
tenantId ID tenanta Microsoft Entra ID.

Pomocí těchto hodnot můžete nakonfigurovat ověřování agentů ve vašem agentu:

Přidejte do .env souboru následující nastavení a nahraďte zástupné hodnoty skutečnými 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á Description Požadováno Příklad
USE_AGENTIC_AUTH Povolení režimu ověřování agentů Ano true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID ID klienta podrobného plánu agenta z a365 config display -g Ano 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Tajný klíč klienta podrobného plánu agenta z a365 config display -g Ano abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID ID tenanta Microsoft Entra z a365 config display -g Ano adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

Poznámka:

V případě .NET se také ujistěte USE_AGENTIC_AUTH=true , že je nastavená launchSettings.json (viz krok 4: Referenční informace o proměnných prostředí)

Krok 2: Proměnné 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í – Požadovaná nastavení pro ověřování agentů
  • Konfigurace koncového bodu MCP – Určení koncového bodu platformy agenta 365
  • Proměnné pozorovatelnosti – Povolení protokolování a distribuovaného trasování
  • Konfigurace aplikačního serveru agenta – Konfigurace portu, na kterém běží server agenta

Proměnné ověřování

Nakonfigurujte nastavení obslužné rutiny ověřování, která jsou potřebná pro správné fungování ověřování agentů.

Přidejte do .env souboru:

# 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á Description Požadováno
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Typ obslužné rutiny ověřování Ano
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Obory ověřování pro Microsoft Graph Ano
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Alternativní název připojení podrobného plánu Ano
CONNECTIONSMAP_0_SERVICEURL Model adresy URL služby pro mapování připojení Ano
CONNECTIONSMAP_0_CONNECTION Název připojení pro mapování Ano

Ověření konfigurace koncového bodu

Konfigurace koncového bodu MCP (Model Context Protocol) je nutná k určení koncového bodu platformy Agent 365, ke kterému se má váš agent připojit. Když vygenerujete manifest nástrojů, který definuje servery nástrojů pro vašeho agenta, musíte zadat koncový bod platformy MCP. Tento koncový bod určuje, k jakému prostředí (předprodukčnímu, testovacímu nebo produkčnímu) se servery nástrojů MCP připojují pro možnosti integrace Microsoftu 365.

Přidejte do .env souboru:

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

Důležité: Pokud MCP_PLATFORM_ENDPOINT není zadáno, nastaví se jako výchozí produkční koncový bod.

Proměnné pozorovatelnosti

Nakonfigurujte tyto požadované proměnné, abyste povolili protokolování a distribuované trasování pro vašeho agenta. Další informace o funkcích pozorovatelnosti a osvědčených postupech

Poznámka:

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

Proměnná Popis Výchozí Příklad
ENABLE_A365_OBSERVABILITY Povolení nebo zakázání pozorovatelnosti false true
ENABLE_A365_OBSERVABILITY_EXPORTER Export trasování do služby pozorovatelnosti false true
OBSERVABILITY_SERVICE_NAME Název služby pro trasování Jméno agenta my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE Namespace = RouteService agent365-samples my-company-agents

Konfigurace aplikačního serveru agenta

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

Přidejte do .env souboru:

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

Instalace závislostí a spuštění aplikačního serveru agenta

Po nakonfigurování prostředí je potřeba nainstalovat požadované závislosti a spustit aplikační server agenta místně pro účely testování.

Instalace závislostí:

uv pip install -e .

Tento příkaz přečte závislosti balíčků definované v pyproject.toml a nainstaluje je z PyPI. Při vytváření aplikace agenta od začátku je potřeba vytvořit pyproject.toml soubor pro definování závislostí. Ukázkové agenty z úložiště ukázek už mají tyto balíčky definované. Řádky můžete podle potřeby aktualizovat, přidávat nebo odstraňovat.

Spuštění aplikačního serveru agenta

python <main.py>

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

Nebo použijte uv:

uv run python <main.py>

Váš server agenta by teď měl být spuštěný a připravený přijímat požadavky z aplikací Agents Playground nebo Microsoft 365.

Ladění a testování agenta v testovacím prostředí agentů

Agents Playground je místní testovací nástroj, který simuluje prostředí Microsoftu 365 bez nutnosti úplné instalace tenanta. Je to nejrychlejší způsob, jak ověřit logiku agenta a vyvolání nástrojů. Další informace naleznete v tématu Test with Agents Playground.

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

agentsplayground

Otevře se webový prohlížeč s rozhraním Agents Playground. Nástroj zobrazí rozhraní chatu, ve kterém můžete odesílat zprávy agentům.

Základní testy

Začněte tím, že ověříte, že je agent správně nakonfigurovaný. Odešlete agentu zprávu:

What can you do?

Agent by měl odpovídat podle pokynů, se kterými je nakonfigurovaný, na základě systémových výzev a možností vašeho agenta. To potvrzuje, že:

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

Vyvolání testovacích nástrojů

Po dokončení konfigurace serverů toolingManifest.json nástrojů MCP (viz Nástroje pro pokyny k nastavení), vyvolání testovacích nástrojů s příklady, jako jsou tyto:

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

List all tools I have access to

Pak otestujte vyvolání konkrétního nástroje:

Nástroje pošty

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í odeslání zprávy.

Nástroje kalendáře

List my calendar events for today

Očekávaná odpověď: Agent načte a zobrazí události kalendáře pro aktuální den.

Nástroje SharePointu

List all SharePoint sites I have access to

Očekávaná odpověď: Agent se dotazuje na SharePoint a vrátí seznam webů, ke kterým máte přístup.

Vyvolání nástroje můžete zobrazit v:

  • Okno chatu – podívejte se na odpověď agenta a všechna volání nástrojů.
  • Panel Protokol – zobrazení podrobných informací o aktivitě včetně parametrů nástroje a odpovědí

Testování s aktivitami oznámení

Během místního vývoje můžete otestovat scénáře oznámení simulací vlastních aktivit v agentech Playground. To vám umožní před nasazením do produkčního prostředí ověřit zpracování oznámení vašeho agenta.

Před testováním aktivit oznámení se ujistěte, že máte:

  • Nakonfigurovali požadované servery nástrojů MCP ve vašem toolingManifest.jsonpočítači . Další informace o nástrojích
  • Povolení oznámení pro agenta Naučte se nastavit oznámení.

Oznámení vyžadují správnou konfiguraci nástroje i nastavení oznámení, aby fungovala správně. Pomocí funkce vlastní aktivity můžete otestovat scénáře, jako jsou e-mailová oznámení nebo komentáře ve Wordu.

Odesílání vlastních aktivit:

  1. Ladění a testování agenta v testovacím prostředí agentů
  2. Ve službě Agents Playground přejděte na napodobení vlastní aktivity aktivity>.
  3. conversationId Zkopírujte z aktivity (ID konverzace se změní pokaždé, když se agenti Dětské hřiště restartují)
  4. Vložte json vlastní aktivity a aktualizujte personal-chat-id pole s ID konverzace, které jste zkopírovali. Příklad e-mailového oznámení
  5. Vyberte Přidat aktivitu.
  6. Zobrazení výsledku v konverzaci chatu i na panelu protokolu

E-mailové oznámení

Tím se simuluje e-mail odeslaný agentovi. Nahraďte zástupné hodnoty skutečnými podrobnostmi agenta:

{
  "type": "message",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2025-09-24T17:40:19+00:00",
  "serviceUrl": "http://localhost:56150/_connector",
  "channelId": "agents",
  "name": "emailNotification",
  "from": {
    "id": "manager@contoso.com",
    "name": "Agent Manager",
    "role": "user"
  },
  "recipient": {
    "id": "agent@contoso.com",
    "name": "Agent",
    "agenticUserId": "<your-agentic-user-id>",
    "agenticAppId": "<your-agent-app-id>",
    "tenantId": "<your-tenant-id>"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "id": "personal-chat-id"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-US",
  "attachments": [],
  "entities": [
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "type": "emailNotification",
      "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "conversationId": "personal-chat-id",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\" style=\"font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\">\nYour email message content here</div>\n\n\n</body>"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    }
  },
  "listenFor": [],
  "textHighlights": []
}

Zobrazení protokolů pozorovatelnosti

Pokud chcete zobrazit protokoly pozorovatelnosti během místního vývoje, instrumentujte agenta s kódem pozorovatelnosti (viz pozorovatelnost pro příklady kódu) a nakonfigurujte proměnné prostředí, jak je popsáno v proměnných pozorovatelnosti. Po nakonfigurování se trasování v reálném čase zobrazí v konzole se zobrazenými informacemi:

  • Trasování volání agenta
  • Podrobnosti o provádění
  • Volání odvození LLM
  • Vstupní a výstupní zprávy
  • Využití tokenů
  • Čas odpovědi
  • Informace o chybě

Tyto protokoly vám pomůžou ladit problémy, porozumět chování agenta a optimalizovat výkon.

Řešení problému

Tato část obsahuje řešení běžných problémů, se kterými se můžete setkat při místním testování agenta.

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

Tyto problémy se týkají problémů s připojením k síti, konflikty portů a nastavením prostředí, které můžou zabránit správné komunikaci agenta.

Problémy s připojením k agentům Playground

Příznak: Agenti Playground se nemůžou připojit k vašemu agentovi

### Řešení:

  • Ověřte, že je spuštěný server agenta.
  • Zkontrolujte, jestli se čísla portů shodují mezi vaším agentem a agenty Playground.
  • Ujistěte se, že žádná pravidla brány firewall neblokují přístup ke kontejneru objektů Blob.
  • Zkuste restartovat agenta i agenta Playground.

Zastaralá verze agentů Playground

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

Řešení: Odinstalace a přeinstalace Agents Playground:

winget uninstall agentsplayground
winget install agentsplayground

Konflikty portů

Příznak: Chyba označující, že port se už používá

### Řešení:

  • Zastavte všechny ostatní instance vašeho agenta.
  • Změna portu v konfiguraci
  • Ukončete všechny procesy pomocí portu:
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

Nejde přidat DeveloperMCPServer

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

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

Authentication issues

K těmto problémům dochází, když se váš agent nemůže správně ověřit ve službách Microsoftu 365 nebo když vypršela platnost přihlašovacích údajů nebo jsou nesprávně nakonfigurované.

Platnost nosného tokenu vypršela

Příznak: Chyby ověřování nebo neautorizované odpovědi 401

Řešení: Nosné tokeny vyprší přibližně po 1 hodině. Získejte nový token a aktualizujte konfiguraci.

Chyby ověřování agentů v Pythonu

Příznak: Chyba při získávání tokenu instance agenta

Řešení: Ověřte ALT_BLUEPRINT_NAME.envnastavení v :

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

Známé problémy a oznámení

Tyto problémy zahrnují problémy s vyvoláním nástrojů, interakcemi serveru MCP a doručováním oznámení.

Nechodí e-maily

Příznak: Agent indikuje, že se odeslal e-mail, ale neobdržíte ho

### Řešení:

  • Zkontrolujte složku s nevyžádanou poštou.
  • Doručení e-mailu může být zpožděno o několik minut – počkejte až 5 minut.
  • Ověření správnosti e-mailové adresy příjemce
  • Kontrola chyb při odesílání e-mailů v protokolech agenta

Odpovědi komentářů ve Wordu nefungují

Známý problém: Služba oznámení momentálně nemůže reagovat přímo na komentáře aplikace Word. Tato funkce se vyvíjí.

Získání nápovědy

Pokud narazíte na problémy, které nejsou popsané v této části řešení potíží, projděte si tyto zdroje informací:

Úložiště sady Microsoft Agent 365 SDK

Další podpora

Další kroky

Teď, když jste úspěšně otestovali agenta místně, jste připraveni ho nasadit do Azure a publikovat ho do Microsoftu 365:

  • Nasazení a publikování agentů: Zjistěte, jak nasadit agenta do webové aplikace Azure a publikovat ho do Centra pro správu Microsoftu a zpřístupnit ho vaší organizaci ke zjišťování a přijímání v Microsoftu 365.
  • Last updated on