Jeden SDK klient pro obě běhová prostředí Copilot Studio: zatím v preview

V článku Ruční ověřování pravděpodobně nepotřebujete jsem ukázal, jak můžete agenta Copilot Studio začlenit do vlastní aplikace s přihlašováním přes Microsoft Entra ID, a přitom u agenta ponechat nastavení Authenticate with Microsoft. Vaše aplikace využívá k přihlašování registraci aplikace v Microsoft Entra a ke komunikaci s agentem Microsoft 365 Agents SDK.

Co když ale Váš agent používá běhové prostředí GitHub Copilot, označované jako harness?

Nová verze klienta Copilot Studio přidává podporu tohoto prostředí. Pro obě prostředí používáte stejného klienta. Stačí předat ID prostředí a název schématu agenta a dál používat stejné metody pro práci s konverzací.

Podpora je již součástí klientů pro JavaScript a .NET, podpora Pythonu se plánuje. Zde použiji JavaScript, protože budu rozšiřovat ukázkovou aplikaci v Reactu.

Preview, říjen 2026: V tomto příkladu používám JavaScript klienta 1.10.0-beta.8.g158a2c07ad. Oficiální přehled integrace stále uvádí, že agenti s běhovým prostředím GitHub Copilot nejsou oficiálně podporováni. Berte proto tento příklad jako preview.

Koncové body tohoto klienta se stále postupně zavádějí do jednotlivých regionů. Testování proto začněte v prostředí s předběžným vydáním.

Jak vypadá rozhraní WebChat

WebChat již podporuje streamování, přizpůsobitelný přepis konverzace a rozbalitelné skupiny aktivit. Díky tomu nemusím psát podstatnou část uživatelského rozhraní chatu. WebChat ale není povinný. Pokud již máte frontend, který Vám vyhovuje, použijte SDK v něm.

Agenti s běhovým prostředím GitHub Copilot mohou vedle odpovědí odesílat také aktivity zachycující uvažování a volání nástrojů. Klient tyto aktivity zpřístupňuje Vaší aplikaci. Následující příklad ukazuje WebChat při zpracování požadavku agentem se sbalenými podrobnostmi aktivit:

Agent pracuje na požadavku, podrobnosti aktivit jsou sbalené.

Pokud chcete zobrazit podrobnosti, rozbalte skupinu. Uvidíte kroky uvažování a použití nástrojů:

Rozbalené zobrazení s uvažováním a voláním Get items označeným jako Finished.

Použití ukázkové aplikace v Reactu

Stávající ukázková aplikace React WebChat obsahuje přihlašování přes Microsoft a motiv Fluent. Uvažování ani volání nástrojů nezobrazuje, jejich zobrazení ale doplním dále v článku.

Budete potřebovat Node.js 22. Stáhněte ukázkovou aplikaci a aktualizujte její závislosti:

git clone https://github.com/microsoft/Agents.git
cd Agents
git checkout 1544bcae38f8865b1f095ffcf8df51561e302065
cd samples/nodejs/copilotstudio-webchat-react
npm install --save-exact \
  @microsoft/agents-copilotstudio-client@1.10.0-beta.8.g158a2c07ad \
  @microsoft/agents-activity@1.10.0-beta.8.g158a2c07ad \
  botframework-webchat@4.19.2 \
  botframework-webchat-fluent-theme@4.19.2 \
  rxjs@7.8.2

Zvolil jsem konkrétní revizi ukázkové aplikace a přesné verze balíčků, abyste vycházeli ze stejného kódu. WebChat a jeho motiv Fluent ponechte ve shodných verzích. Informaci o tom, kdy se tato podpora objeví ve stabilním vydání, najdete v poznámkách k vydáním JavaScript klienta.

Připojení k Vašemu agentovi

Budete potřebovat publikovaného agenta s ověřováním nastaveným na Authenticate with Microsoft a uživatele, který k němu má přístup.

Při registraci aplikace postupujte podle pokynů k ukázkové aplikaci:

1. V tenantovi agenta vytvořte registraci aplikace v Microsoft Entra nebo použijte existující.
2. Zaregistrujte http://localhost:3000 jako URI pro přesměrování typu Single-page application.
3. Přidejte Power Platform API > Delegated permissions > CopilotStudio.Copilots.Invoke a zajistěte souhlas podle požadavků Vaší organizace.

V prohlížeči nepotřebujete tajný klíč klienta ani nemusíte přepínat na ruční ověřování. Podrobnosti o oprávněních obsahuje průvodce integrací SDK.

Uživatelské rozhraní běhového prostředí GitHub Copilot zatím nenabízí koncový bod SDK, který byste mohli zkopírovat. Budete potřebovat nastavení pro klienta a pro přihlašování ukázkové aplikace pomocí Microsoft Authentication Library (MSAL):

Hodnota	Kde se používá	Kde ji najdete
ID prostředí	Klient Copilot Studio	Hodnota za /environments/ v URL Vašeho prostředí Copilot Studio
Název schématu agenta	Klient Copilot Studio	Běhové prostředí GitHub Copilot: … > Settings > Agent details. Standardní běhové prostředí: Settings > Advanced > Metadata
ID tenanta a ID aplikace/klienta	Přihlašování SPA (MSAL)	Stránka Overview v registraci Vaší aplikace v Microsoft Entra

Použijte tlačítko pro kopírování. Název schématu může být delší, než kolik znaků pole dokáže zobrazit.

Vytvořte soubor src/settings.js. Ukázková aplikace v něm ukládá obě sady nastavení. MSAL zajišťuje přihlášení a získává přístupový token, který aplikace předává klientovi Copilot Studio:

import {
  AgentType, ConnectionSettings, PowerPlatformCloud
} from '@microsoft/agents-copilotstudio-client'
export class SampleConnectionSettings extends ConnectionSettings {
  constructor () {
    super({
      environmentId: 'YOUR_ENVIRONMENT_ID',
      schemaName: 'YOUR_AGENT_SCHEMA_NAME',
      cloud: PowerPlatformCloud.Prod,
      copilotAgentType: AgentType.Published
    })
    // Používá pomocný modul ukázkové aplikace pro přihlašování přes MSAL.
    this.tenantId = 'YOUR_TENANT_ID'
    this.appClientId = 'YOUR_APP_CLIENT_ID'
    this.authority = 'https://login.microsoftonline.com'
  }
}

Použijte PowerPlatformCloud.Prod a hodnotu directConnectUrl nenastavujte.

Spusťte npm start, otevřete http://localhost:3000 a přihlaste se. Nyní byste měli být schopni s agentem chatovat.

JavaScript klienta jsem otestoval s publikovaným agentem na každém z obou běhových prostředí, ve stejném prostředí Power Platform a se stejnou registrací aplikace. Změnil jsem pouze schemaName. Oba agenti vraceli streamované aktivity a odpověděli na pozdrav i navazující zprávu v rámci stejné konverzace.

Zobrazení uvažování a volání nástrojů

Nyní přidám zobrazení uvažování a volání nástrojů ze snímků obrazovky.

WebChat již obsahuje rozbalitelné skupiny aktivit, takže není nutné vytvářet samostatný panel pro uvažování. Stačí převést entity uvažování a volání nástrojů ze SDK do formátu, který WebChat očekává.

Toto rozšíření prozatím slouží k pochopení a demonstraci toho, jak se uvažování a volání nástrojů zobrazují. Další hotové možnosti chatového rozhraní mají následovat.

K článku jsem přiložil dva pomocné moduly a náhradní soubor Chat.tsx. Uložte je do adresáře src/ ukázkové aplikace v Reactu:

• activityDetails.ts: shromažďuje aktualizace uvažování a změny stavů nástrojů.
• agentActivity.ts: propojuje tyto aktualizace s nativními skupinami WebChat.
• Chat.tsx: kompletní náhradní komponenta včetně přihlašování, zobrazení chyb a úklidu prostředků připojení.

Stávající soubor acquireToken.ts ponechte. Mění se způsob zobrazování aktivit, nikoli přihlašování. Soubory ke stažení jsou poskytovány pod licencí MIT.

Obalení připojení pomocnou funkcí

V souboru Chat.tsx importujte pomocnou funkci:

import { createAgentActivityConnection } from './agentActivity'

Poté ji použijte místo CopilotStudioWebChat.createConnection:

const client = new CopilotStudioClient(settings, token)
const next = createAgentActivityConnection(
  client,
  { showReasoning: true, showToolCalls: true },
  {
    onBusyChange: setBusy,
    onError: failure => setError(failure.message)
  }
)
setConnection(next)

setBusy a setError jsou funkce pro nastavení stavu v komponentě ke stažení. Volby showReasoning a showToolCalls patří k pomocné funkci, nikoli k SDK. Můžete zapnout kteroukoli z nich, obě, nebo žádnou.

Vykreslení pomocí WebChat

Vykreslování nadále využívá komponenty Fluent z ukázkové aplikace:

<FluentThemeProvider variant="copilot">
  <Composer
    directLine={connection}
    disabled={busy || Boolean(error)}
    styleOptions={styleOptions}
  >
    <BasicWebChat />
  </Composer>
</FluentThemeProvider>

V úplné komponentě zůstává styleOptions mimo komponentu a nastavuje partGroupDefaultOpen: false. Vypnul jsem také nahrávání souborů, aby se tento příklad soustředil na chat.

Co agent vrací

Pomocný modul zpracovává aktivity SDK následujícím způsobem:

Obsah	Zobrazení
Text odpovědi, streamovaný nebo úplný	Běžná odpověď ve WebChat
Entita thought	Krok uvažování využívající hodnotu text dané entity
Entita toolCall	Pojmenovaný krok přiřazený podle toolCallId, se stavem Started, Finished nebo Failed

Jak postupně přichází text uvažování, pomocný modul aktualizuje existující krok, místo aby pro každý fragment přidával novou zprávu. Pokud agent zavolá stejný nástroj dvakrát, jde stále o dvě samostatná volání. Každé kolo konverzace má vlastní skupinu a přerušená kola jsou označena jako přerušená.

Modul zpracovává také události nástrojů ve starším formátu. Běžné zprávy a navrhované odpovědi předává beze změny. Argumenty nástrojů, jejich výsledky a neveřejná metadata plánovače se do přehledu aktivit nezobrazují.

showReasoning pouze zobrazuje uvažování, které služba odešle klientovi. Nezapíná uvažování u agenta ani nepovažuje každou aktualizaci průběhu za krok uvažování. To, co klient obdrží, závisí na běhovém prostředí a modelu.

Pokud chcete změnit vykreslování samotných zpráv, možnosti rozšíření popisuje průvodce middlewarem WebChat.