Del via

Udvid din agent med værktøjer fra en REST API (prøveversion)

[Denne artikel er til dokumentationen til den foreløbige udgivelse. Der kan forekomme ændringer.]

Du kan bruge REST API'er (herunder OpenAI API) til at forbinde en agent, du opretter, med eksterne systemer og få adgang til tilgængelige data til brug i din agent. Du kan knytte din agent til en REST-API ved at angive Copilot Studio tre ting:

  • En OpenAPI specifikation, der definerer API'ens funktioner og tilgængelige handlinger
  • Detaljer om den type godkendelse, der er nødvendig, og godkendelsesdetaljer for brugere, der skal oprette forbindelse til API'en for at få adgang til det eksterne system
  • Beskrivelser, der hjælper sprogmodellen med at bestemme, hvornår API'en skal aktiveres for at udnytte dataene

REST API'er kan føjes til Copilot-agenter og brugerdefinerede agenter gennem Copilot Studio.

Important

Denne artikel indeholder dokumentation til forhåndsversionen af Microsoft Copilot Studio. Der kan forekomme ændringer.

Forhåndsversionsfunktionerne er ikke beregnet til produktionsformål og kan have begrænset funktionalitet. Disse funktioner er tilgængelige før en officiel udgivelse, så du kan få tidlig adgang og give feedback.

Hvis du skal bygge en produktionsklar agent, kan du se Oversigt over Microsoft Copilot Studio.

Copilot-agenter giver en udvikler mulighed for at kombinere flere datakilder, f.eks. connectorer, API'er, prompter og videnkilder, i en enkelt agent. Du kan bruge denne agent til at udvide Microsoft-brandede agentoplevelser som Microsoft 365 Copilot.

Brugerdefinerede agenter er selvstændige agenter, der indeholder connectorer, API'er, prompter og videnkilder. Du kan bruge brugerdefinerede agenter direkte ved at integrere dem på websteder eller i andre kanaler.

Bemærk

REST API-værktøjer skal oprettes ud fra en OpenAPI v2-specifikation. Dette krav skyldes funktionsmåden i Power Platform under behandling af API-specifikationer. Hvis der indsendes en v3-specifikation, oversættes den automatisk til en v2-specifikation under oprettelsesprocessen.

Forudsætninger

  • Maker-niveau legitimationsoplysninger og en Copilot Studio-licens.
  • En kopi af OpenAPI-specifikationen for det REST API, du vil forbinde til
  • Kendskab til den type autentificering, der er nødvendig for at forbinde til API'en, samt autentificeringsdetaljerne.

Tilføj et REST API-værktøj til din agent

At tilføje et REST API-værktøj til din agent involverer et par trin:

  1. Tilføj et nyt agentværktøj og vælg REST API
  2. Giv API-specifikation, beskrivelse og løsning
  3. Giv autentificeringsoplysninger
  4. Vælg værktøjer fra API'en
  5. Gennemgå og udgiv

De følgende afsnit guider dig gennem processen, trin for trin.

Processen for at tilføje et REST API er identisk for både brugerdefinerede agenter og agenter til Microsoft 365 Copilot.

Tilføj et nyt agentværktøj og vælg REST API

  1. Gå til oversigtssiden for din agent.

  2. I afsnittet Værktøjer skal du vælge Tilføj værktøj. Du kan også gå til fanen Funktioner og vælge Tilføj et værktøj.

    Siden Tilføj værktøj vises.

  3. Vælg Nyt værktøj REST>API.

Angiv API-specifikation, -beskrivelse og -løsning

  1. Upload en OpenAPI specifikationsfil for den REST API, du vil oprette forbindelse til. Du kan enten trække og slippe specifikationsfilen til skærmen Upload en REST API eller gennemse dit system for at finde den fil, du vil bruge.

    Upload API-specifikation.

    Bemærk

    Specifikationen OpenAPI skal være en JSON-fil i v2-format. Hvis der indsendes en v3-specifikation, oversættes den automatisk til en v2-specifikation under oprettelsesprocessen.

    Når du har overført specifikationen, opdateres skærmbilledet for at angive specifikationens filnavn og detaljerne.

    Uploadet API-specifikation.

    I de følgende trin jorder vi proceduren i et specifikt eksempel på SunnyADO, et ADO-billetstyringssystem. I eksemplet er hensigten at give brugerne mulighed for at hente og opdatere deres anmodninger via agenten.

  2. Kontrollér oplysningerne, og vælg Næste.

    Du får vist en side med oplysninger om API-plugin, hvor du kan angive yderligere oplysninger om API'en.

    Detaljer om API-plug-in.

    Beskrivelsesfeltet udfyldes indledningsvis på baggrund af beskrivelsen i den API-specifikation, du har uploadet. Angiv en detaljeret beskrivelse, da agentorkestrering bruger beskrivelsen til at bestemme, hvornår du skal bruge det pågældende værktøj. Angiv detaljer, herunder synonymer, for at hjælpe din agent med udvælgelsesprocessen.

    For eksempel er den oprindelige beskrivelse: "En simpel service til at administrere billetter."

    En bedre beskrivelse er: "Et system, der bruges til at hente, finde og vise eksisterende anmodninger fra SunnyADO." Det giver brugerne mulighed for at opdatere, ændre og administrere billetter for at give flere data for at forbedre posterne.

  3. Indtast en forbedret beskrivelse under feltet Beskrivelse.

  4. Under Løsninger indeholder en rulleliste alle løsninger, der er tilgængelige i det aktuelle miljø. Vælg den løsning, du vil bruge. Du kan finde flere oplysninger om, hvad løsninger er, i Løsningskoncepter.

    Vælg en løsning.

    Hvis du har en foretrukken løsning, eller hvis den valgte connector allerede findes i løsningen, vælges denne løsning automatisk.

    Du kan enten vælge en løsning eller lade den være tom. Hvis du lader løsningen være tom, oprettes der en løsning til dig med handlingsnavnet og standardudgiveren. Når du gemmer din handling i en løsning, kan du let flytte den på tværs af miljøer.

    Bemærk

    Hvis du ikke kan se standardløsningen eller CDS-standardløsningen som en mulighed i dette tilfælde, anbefaler vi, at du har en brugerdefineret løsning, der gør det nemt at administrere. Flere oplysninger i: Standardløsning vs. brugerdefineret løsning.

  5. Når der er valgt en løsning, skal du vælge Næste for at fortsætte.

Angive godkendelsesoplysninger

Siden Godkendelse vises, hvor du kan vælge, hvilken type godkendelse der skal bruges til API'en.

Vælg godkendelsesmetode.

  1. Vælg en godkendelsesmetode på listen. Der er tre valgmuligheder:

    • Ingen: Ingen autentificering er nødvendig for at få adgang til API'et.
    • API-nøgle: Vælg denne mulighed, hvis dit API kræver en API-nøgle til autentificering. Under runtime, når agenten ønsker at bruge API-værktøjet, beder agenten brugeren om at autentificere. Brugeren angiver en API-nøgle, og agenten forbinder til API'et ved hjælp af den nøgle.
    • Auth 2.0: Vælg denne mulighed, hvis din MCP-server bruger OAuth 2.0 til autentificering. OAuth 2.0 lader individuelle brugere autentificere sig til API'et via en identitetsudbyder. Dette giver brugeren tilladelser til din applikation (agent) uden at dele deres legitimationsoplysninger med agenten.

  2. Indtast de nødvendige felter for den valgte autentificeringsmetode. Felterne varierer, afhængigt af godkendelsesmetoden.

    • Ingen: Ingen information at give.
    • API-nøgle:
      • Parameteretiket: En tekstetiket til API-parameteren, som skal præsenteres for brugerne.
      • Parameternavn: Det faktiske navn for API-nøgleparameteren, der skal bruges enten i headeren eller forespørgselsstrengen.
      • Parameterplacering: Hvordan du skal sende nøglen til API'en. Vælg enten Header eller Forespørgsel.
    • Godkendelse 2.0:
      • Klient-id: Klient-id'et fra identitetsudbyderen, som udstedes til dig, når du registrerer din app. Klient-id'et giver identitetsudbyderen besked om, hvilken app der foretager anmodningen.
      • Klienthemmelighed: Klienthemmeligheden, som identitetsudbyderen udsteder, når du registrerer din app. Din agent sender klienthemmeligheden sammen med klient-id'et for at bevise, at din agent er autoriseret til at anmode om adgangstokens til MCP-serveren.
      • GODKENDELSEs-URL-adresse: Slutpunktet for identitetsudbyderen, hvor din agent omdirigerer brugeren til at logge på og tildele tilladelser til din agent (samtykkekort, der vises i agentchatten). Brugeren godkender her, og identitetsudbyderen svarer derefter tilbage til agenten på URL-adressen til tilbagekald med en godkendelseskode.
      • Token URL: Det endpoint, hvor din agent udveksler autorisationskoden (eller refresh token) for en access token og refresh token. Adgangstokenet gør det muligt for din agent at bruge MCP-serveren på vegne af brugeren. Med opdateringstokens kan din agent få ny adgang og opdatere tokens fra opdateringsslutpunktet, når det forrige adgangstoken udløber.
      • Opdater URL-adresse: Slutpunktet for at anmode om et nyt adgangstoken ved hjælp af et opdateringstoken (så brugeren ikke behøver at logge på igen, når tokenet udløber).
      • Scope: (Valgfrit): De tilladelser, din app beder om, som en pladsadskilt liste.
      • Hvilken Microsoft 365-organisation der tilgår endepunkterne: Dette begrænser adgangen til kildekoden til enten producentens organisation eller alle organisationer. Vælg enten:
        • Kun min organisation
        • Alle Microsoft 365-organisationer
      • Hvilken app (klient) kan bruge endepunkterne: GUID, der definerer klientsystemet, der kan bruges til at tilgå disse data. Apps kan omfatte Microsoft 365 Power Automate og andre muligheder.

  3. Når alle felter er udfyldt, skal du vælge Næste.

    Du får vist en side med Vælg og konfigurér dit værktøj , hvor du kan vælge værktøjer, der skal aktiveres fra API'en.

    Vælg API-værktøjer, der skal aktiveres.

Vælg værktøjer fra API'en

Vælg de API-understøttede værktøjer fra REST API'en, som du vil tilføje til din agent. Generelt tilbyder et REST API en række værktøjer gennem de forskellige kombinationer af endpoint- og HTTP-metoder (get, put, post, delete osv.), som er defineret i API-specifikationen. I nogle tilfælde ønsker du måske ikke, at agentens brugere skal have mulighed for at udføre enhver handling, som API'en generelt tilbyder. For eksempel kan din API-specifikation indeholde muligheden for at opdatere og slette, men du vil kun have, at brugere af din agent kan oprette poster.

  1. Vælg et værktøj på listen, der skal konfigureres.

    Siden 'Konfigurer dit værktøj' vises.

    Konfigurer API-værktøj.

  2. Konfigurer navn og beskrivelse for det valgte værktøj. Ligesom med det overordnede API bliver du bedt om at oplyse et værktøjsnavn og en værktøjsbeskrivelse. Beskrivelserne udfyldes indledningsvist på forhånd fra beskrivelserne i API-specifikationen. Navnet behøver ikke at være entydigt, men det skal repræsentere selve værktøjet. Beskrivelsen, ligesom den overordnede API-beskrivelse, bør være specifik nok til at give sprogmodellen detaljer, så den bedre kan identificere, om din forespørgsel stemmer overens med dette specifikke værktøj.

  3. Når felterne er udfyldt, skal du vælge Næste.

    Siden Gennemse værktøjets parametre vises.

    Gennemgå handlingsparametre.

    Denne side viser de værdier, der forventes for input, og de outputværdier, der returneres. Du kan ikke ændre disse værdier, men du kan opdatere beskrivelserne af input og output. Alt indhold på denne side hentes direkte fra den uploadede API-specifikation.

  4. Opdater beskrivelserne efter behov. Beskrivelserne indeholder en definition af, hvad værdierne bruges til. Hvis nogen af beskrivelserne er tomme, skal de udfyldes, før du kan gå videre. Du kan indsætte navnet, hvis du ikke har en bedre beskrivelse.

  5. Når du har fuldført beskrivelserne, skal du vælge Næste.

    Det første værktøj er nu konfigureret og vises på listen over valgte værktøjer på siden Vælg og konfigurer plug-inværktøjet .

    Vis valgte API-handlinger.

  6. Tilføj eventuelle andre værktøjer fra API'et, som du ønsker at inkludere på nuværende tidspunkt. Når du er færdig med at tilføje værktøjer, som din agent skal understøtte, skal du vælge Næste.

    Siden Gennemse dit værktøj vises. Siden indeholder oplysninger om det konfigurerede REST API-værktøj.

    Gennemse det konfigurerede REST API-værktøj.

Gennemgå og publicere

  1. Hvis du har brug for at foretage opdateringer, kan du vælge Tilbage og foretage dine ændringer. Ellers skal du vælge Næste.

    Der vises en skærm, der angiver, at dit værktøj udgives, mens processen er ved at blive fuldført. Du underrettes, når publiceringen er fuldført.

  2. Vælg Opret forbindelse for at fortsætte. Du vender tilbage til Tilføj værktøjsskærmen .

  3. Vælg REST API i værktøjstypevælgeren. Du kan se de nyoprettede værktøjer fra dit API. Der burde være én post for hvert værktøj, du tilføjede fra API'en.

  4. For hvert af de nykonfigurerede værktøjer fra API'en skal du oprette eller vælge en forbindelse til API'et og tilføje værktøjet til din agent:

    1. På skærmen Tilføj værktøj skal du vælge værktøjet.
    2. Under Forbindelse skal du vælge en eksisterende forbindelse eller vælge Opret ny forbindelse.
    3. Indtast alle nødvendige oplysninger til forbindelsen, og vælg derefter Opret for at oprette forbindelsen til værktøjet.
    4. Vælg Add og configure for at tilføje værktøjet til din agent.

    Tilføj nyt REST API-værktøj.

Værktøjerne fra REST API'en er nu tilgængelige til brug i din agent.

Tip

Du kan nemmere finde dit værktøj ved at bruge søgelinjen til at finde det.

  • Last updated on