Deinen ersten Declarative Agent bauen mit Schema v1.4 und v1.5

Ich hab letzte Woche den Großteil meiner Zeit damit verbracht, einen internen Knowledge Agent für einen Kunden neu aufzubauen. Die hatten ein funktionierendes v1.3 Manifest, hat seinen Job gemacht, aber sie wollten zwei Dinge: Der Agent soll aufhören mit eigenem Modellwissen zu halluzinieren, und er soll Kontext aus Teams Meetings ziehen können. Wie sich herausstellt, ist genau beides in den neuesten Schema-Versionen gelandet. Also dachte ich mir, ich schreib das auf solang es noch frisch ist.

Dieser Post geht das Declarative Agent Manifest Schema v1.4 und v1.5 durch – was sich geändert hat, was neu ist, und wie man einen Agent von Grund auf damit baut.

Was sich in v1.4 geändert hat

Schema v1.4 hat ein paar Sachen auf v1.3 draufgepackt:

behavior_overrides – eine neue Top-Level Property, mit der du Suggestions steuern und Model Knowledge unterdrücken kannst.
disclaimer – zeigt Usern am Anfang jeder Konversation eine Disclaimer-Nachricht an.
part_type und part_id auf dem SharePoint IDs Object – du kannst jetzt Teile eines SharePoint Items referenzieren, zum Beispiel eine bestimmte OneNote Page.
ScenarioModels Capability – erlaubt Agents task-spezifische Fine-Tuned Models zu nutzen.
Neue Connection Object Properties, um Copilot Connector Content genauer einzugrenzen.

Die behavior_overrides Property ist in der Praxis die wichtigste. So schaut das aus:

{
  "behavior_overrides": {
    "suggestions": {
      "disabled": true
    },
    "special_instructions": {
      "discourage_model_knowledge": true
    }
  }
}

Wenn du discourage_model_knowledge auf true setzt, sagst du dem Agent, er soll das eingebaute Wissen des LLM beim Generieren von Antworten vermeiden. Er bleibt bei den Knowledge Sources, die du definiert hast. Für Enterprise-Szenarien, wo Antworten strikt auf Firmendaten basieren sollen, war das das meistgefragte Feature, das ich ständig gehört hab.

Die disclaimer Property macht genau das, was man erwarten würde:

{
  "disclaimer": {
    "text": "This agent provides information from internal documentation only. Always verify critical decisions with your team lead."
  }
}

Der Text wird am Anfang jeder Konversation angezeigt. Maximal 500 Zeichen. Simpel, aber Legal- und Compliance-Teams sind damit deutlich glücklicher.

Was sich in v1.5 geändert hat

Schema v1.5 fügt genau eine Sache zu v1.4 hinzu: die Meetings Capability.

{
  "capabilities": [
    {
      "name": "Meetings"
    }
  ]
}

Das war’s. Ein neues Capability Object. Aber das eröffnet einiges – dein Agent kann jetzt Meeting-Metadaten (Betreff, Organisator, Teilnehmer), Transcript-Inhalte und Meeting-Chats durchsuchen. Stell dir einen Projektstatus-Agent vor, der “Was wurde beim Standup letzten Dienstag zum Budget besprochen?” beantworten kann, ohne dass irgendjemand manuell Notizen schreiben muss. Genau das war das Szenario, das mein Kunde wollte.

Die Meetings Capability braucht eine Microsoft 365 Copilot Lizenz für den User. In v1.5 gibt es keine zusätzlichen Scoping Properties – der Agent hat Zugriff auf alle Meetings, auf die der User Zugriff hat. (Falls du auf bestimmte Meetings per UID einschränken musst – das kam erst in v1.6 mit der items_by_id Property.)

Einen Declarative Agent von Grund auf bauen

Wir bauen einen internen Knowledge Agent, der SharePoint Dokumente und Teams Meetings als Knowledge Sources nutzt, Model Hallucination unterdrückt und einen Disclaimer anzeigt. Im Prinzip das Gleiche, was ich für den Kunden gebaut hab, nur etwas vereinfacht.

Voraussetzungen

Du brauchst:

Visual Studio Code
Die Microsoft 365 Agents Toolkit Extension (Version 6.x oder höher)
Einen Microsoft 365 Tenant mit Copilot Lizenzen

Projekt erstellen

VS Code öffnen.
Microsoft 365 Agents Toolkit > Create a New Agent/App auswählen.
Declarative Agent auswählen.
No Action auswählen (wir bauen einen reinen Knowledge Agent).
Einen Ordner wählen und sinnvoll benennen – ich verwende ProjectKnowledgeAgent.

Das Toolkit generiert ein Projekt mit der Hauptdatei unter appPackage/declarativeAgent.json. Das ist unser Manifest.

Das vollständige Manifest

Hier ist das komplette Manifest für unseren Agent. Ich geh danach Abschnitt für Abschnitt durch:

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json",
  "version": "v1.5",
  "name": "Project Knowledge Agent",
  "description": "Answers questions about our project using internal documentation and meeting context.",
  "instructions": "You are a project knowledge assistant. Answer questions based on the SharePoint documents and meeting transcripts provided as knowledge sources. Be concise and cite specific documents or meetings when possible. If you cannot find the answer in the provided sources, say so clearly. Do not speculate or use general knowledge.",
  "conversation_starters": [
    {
      "title": "Project Status",
      "text": "What's the current status of Project Alpha based on the latest documents?"
    },
    {
      "title": "Meeting Recap",
      "text": "Summarize the key decisions from last week's project meetings."
    },
    {
      "title": "Open Items",
      "text": "What action items are still open from our recent meetings?"
    }
  ],
  "behavior_overrides": {
    "suggestions": {
      "disabled": false
    },
    "special_instructions": {
      "discourage_model_knowledge": true
    }
  },
  "disclaimer": {
    "text": "This agent answers based on internal project documents and meeting transcripts only. Always verify critical information with the project lead."
  },
  "capabilities": [
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        {
          "url": "https://contoso.sharepoint.com/sites/ProjectAlpha/Shared Documents"
        }
      ]
    },
    {
      "name": "Meetings"
    },
    {
      "name": "TeamsMessages",
      "urls": [
        {
          "url": "https://teams.microsoft.com/l/channel/19%3Aabc123def456@thread.tacv2/Project%20Alpha?groupId=your-group-id&tenantId=your-tenant-id"
        }
      ]
    }
  ]
}

Schauen wir uns an, was jeder Teil macht.

Schema und Version

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.5/schema.json",
  "version": "v1.5"
}

Die $schema Property zeigt auf die JSON Schema Definition. Setz version auf v1.5, um Zugriff auf sowohl die v1.4 Behavior Overrides als auch die v1.5 Meetings Capability zu bekommen. Nimm v1.4, wenn du keine Meetings brauchst.

Instructions die funktionieren

Das instructions Feld ist der Core Prompt deines Agents. Bis zu 8.000 Zeichen. Ich hab die Erfahrung gemacht, dass es genauso wichtig ist, explizit zu sagen was der Agent nicht tun soll, wie zu sagen was er tun soll. “Do not speculate” und “say so clearly if you can’t find the answer” sind Zeilen, die ich in fast jeden Agent reinschreib.

Ein paar Tipps aus echten Deployments:

Starte mit der Rolle des Agents (“You are a project knowledge assistant”).
Definiere das erwartete Verhalten (“Be concise and cite specific documents”).
Setze Grenzen (“Do not speculate or use general knowledge”).
Halte den Fokus. Einen Agent dazu bringen, alles zu können, ist ein Rezept für mittelmäßige Ergebnisse.

Conversation Starters

Du kannst bis zu 12 Conversation Starters definieren. Jeder braucht eine text Property (erforderlich) und einen optionalen title. Beide sind lokalisierbar. Die werden als Suggestion Chips angezeigt, wenn der User den Agent öffnet – das ist der erste Eindruck, also mach sie spezifisch für das, was der Agent wirklich gut kann.

Knowledge Sources konfigurieren

Declarative Agents unterstützen eine ganze Reihe verschiedener Knowledge Sources, und v1.4/v1.5 geben dir mehr Kontrolle darüber, wie sie eingegrenzt werden.

SharePoint und OneDrive

Die OneDriveAndSharePoint Capability ist wahrscheinlich die meistgenutzte Knowledge Source. Du kannst Inhalte auf zwei Arten referenzieren:

Per URL – auf eine Site, Library oder einen Folder zeigen:

{
  "name": "OneDriveAndSharePoint",
  "items_by_url": [
    {
      "url": "https://contoso.sharepoint.com/sites/ProjectAlpha/Shared Documents"
    }
  ]
}

Per SharePoint IDs – genauer, mit site_id, web_id, list_id und unique_id:

{
  "name": "OneDriveAndSharePoint",
  "items_by_sharepoint_ids": [
    {
      "site_id": "bc54a8cc-8c2e-4e62-99cf-660b3594bbfd",
      "web_id": "a5377427-f041-49b5-a2e9-0d58f4343939",
      "list_id": "78A4158C-D2E0-4708-A07D-EE751111E462",
      "unique_id": "304fcfdf-8842-434d-a56f-44a1e54fbed2"
    }
  ]
}

Neu in v1.4: Du kannst part_type und part_id verwenden, um bestimmte Teile eines SharePoint Items zu referenzieren. Aktuell ist der einzige unterstützte part_type OneNotePart, womit du auf eine bestimmte OneNote Page zeigen kannst. Nischig, aber sehr praktisch, wenn dein Team Projektnotizen in OneNote führt.

Die Realität beim File Limit

Das überrascht viele Leute – und es ist in den Microsoft Learn Best Practices dokumentiert. Du kannst zwar eine große Anzahl von SharePoint Files referenzieren, aber Copilots Retrieval-Verhalten ändert sich je nachdem, wie viele du angibst:

20 oder weniger Files: Copilot durchsucht den gesamten Inhalt aller Files.
Mehr als 20 Files: Copilot durchsucht den gesamten Inhalt der 20 relevantesten Files.

Wenn du also 50 Files angibst, bestimmt Copilot zuerst, welche 20 am relevantesten für die Anfrage des Users sind, und durchsucht dann diese. Die Best Practice von Microsoft ist, die referenzierten Files unter 300 Gesamtseiten zu halten, wenn du gründliche Abdeckung willst.

Auch wichtig: Halte einzelne Files unter 36.000 Zeichen (ungefähr 15-20 Seiten). Größere Files machen es Copilot schwerer, den richtigen Inhalt zu finden. Wenn du ein riesiges Dokument hast, teil es in kleinere, fokussierte Files auf.

Teams Meetings als Knowledge Source

Die Meetings Capability (v1.5) gibt deinem Agent Zugriff auf:

Meeting-Metadaten: Betreff, Organisator, Teilnehmer, Titel
Transcript-Inhalte
Meeting-Chats

In v1.5 ist die Capability unscoped – der Agent kann alle Meetings durchsuchen, auf die der User Zugriff hat. Es gibt in dieser Version keine Property, um auf bestimmte Meetings einzuschränken.

Eins noch im Hinterkopf behalten: Meeting Transcripts sind nur verfügbar, wenn Transcription während des Meetings tatsächlich aktiviert war. Kein Transcript, kein Content den der Agent durchsuchen kann. Stell sicher, dass deine Organisation die Transcription Policies korrekt konfiguriert hat.

Teams Messages

Getrennt von Meetings erlaubt die TeamsMessages Capability dem Agent, durch Channels, Meeting-Chats, Gruppen-Chats und 1:1-Chats zu suchen. Du kannst auf bis zu fünf spezifische URLs eingrenzen, oder das urls Array leer lassen, um alles zu durchsuchen.

{
  "name": "TeamsMessages",
  "urls": [
    {
      "url": "https://teams.microsoft.com/l/channel/19%3A...@thread.tacv2/General?groupId=...&tenantId=..."
    }
  ]
}

Um die URL für einen Channel zu bekommen, rechtsklick auf den Channel-Namen in Teams und “Get link to channel” auswählen. Für Gruppen- oder 1:1-Chats brauchst du das Deep Link Format: https://teams.microsoft.com/l/chat/<chatId>/conversations.

Provisioning und Testen

Sobald dein Manifest fertig ist:

In VS Code die Microsoft 365 Agents Toolkit Sidebar öffnen.
Unter Lifecycle auf Provision klicken.
Mit deinem Microsoft 365 Account anmelden.
Das Toolkit packt dein Manifest zusammen und lädt es hoch.

Zum Testen:

Geh zu https://m365.cloud.microsoft/chat.
Klick auf das Conversation Drawer Icon neben New Chat.
Deinen Agent finden und auswählen.
Probier zuerst deine Conversation Starters, dann stell Fragen, die deine Knowledge Sources treffen sollten.

Ich teste immer in drei Runden:

Happy Path: Fragen, die der Agent gut aus dem vorhandenen Wissen beantworten sollte.
Edge Cases: Fragen, die angrenzen aber nicht direkt abgedeckt sind – gibt der Agent zu, dass er es nicht weiß?
Out of Scope: Fragen komplett außerhalb der Agent-Domäne – mit discourage_model_knowledge auf true sollte der Agent nicht versuchen, diese aus allgemeinem Wissen zu beantworten.

Best Practices fürs Manifest

Nachdem ich ein paar davon gebaut hab, sind das die Dinge, zu denen ich immer wieder zurückkomme.

Die Instructions sind viel wichtiger als man denkt. Vage Instructions produzieren vage Ergebnisse. “Help with project questions” ist schlecht. “Answer questions about Project Alpha timelines, deliverables, and meeting decisions using the provided SharePoint documents and meeting transcripts” ist gut. Investier hier Zeit.

Wenn der Agent nur aus deinen Daten antworten soll, aktivier discourage_model_knowledge. User vertrauen dem Agent mehr, wenn er sagt “Ich hab diese Information nicht”, statt sich was zusammenzureimen. Ich setz das bei jedem Enterprise Agent mittlerweile auf true.

Zeig nicht auf einen ganzen SharePoint Tenant als Knowledge Source. Zeig auf die spezifische Site, Library oder den Folder, der relevant ist. Weniger Rauschen, bessere Antworten. Gleiches Prinzip wie: kippe nicht deinen ganzen File Server in einen Suchindex.

Brich große Dokumente in themenspezifische Files unter 20 Seiten auf. Copilot retrievet besser aus vielen kleinen Files als aus wenigen riesigen. Das hab ich auf die harte Tour gelernt, mit einem 200-seitigen Operations Manual, das der Agent kaum nutzen konnte.

Teste mit echten Fragen – nicht “Was ist Project Alpha?”, sondern die tatsächlichen Fragen, die deine User stellen werden. “Wann ist der nächste Milestone für die Backend Migration?” ist die Art von Query, gegen die du testen solltest.

Wenn dein Agent HR Policies, Finanzdaten oder irgendetwas Reguliertes behandelt, füg einen Disclaimer hinzu. Das dauert zwei Minuten und erspart dir später Kopfschmerzen.

Noch eine Sache: Verwende die neueste Schema-Version, die du tatsächlich brauchst. Nimm nicht v1.5, wenn du keine Meetings brauchst – v1.4 reicht. Aber bleib nicht bei v1.3, wenn du Behavior Overrides brauchst.

Was kommt als Nächstes

Schema v1.5 ist schon nicht mehr die neueste Version – v1.6 hat Scoped Meetings (mit items_by_id), die include_related_content Property für People, und mehr hinzugefügt. Es bewegt sich alles schnell. Aber die Kernideen aus v1.4 und v1.5 – Behavior Overrides, Knowledge Scoping, Capabilities zusammensetzen – gelten nach wie vor in jeder neueren Version. Einmal lernen und du bist gerüstet.

Wenn du darauf gewartet hast, deinen ersten Declarative Agent auszuprobieren: Das Tooling ist gerade in einem guten Zustand. Das Agents Toolkit macht die Feedback Loop schnell genug, dass du an einem Nachmittag von null auf einen funktionierenden Agent kommst.

Bau was. Und dann erzähl mir davon.

Weiterlesen

Declarative Agent Manifest Schema v1.4 Referenz – Microsoft Learn
Declarative Agent Manifest Schema v1.5 Referenz – Microsoft Learn
Declarative Agent Best Practices – Microsoft Learn (Knowledge Source Limits, Instruction-Tipps, Testing Guidance)

Enjoyed this post? Let's connect on LinkedIn:

Follow on LinkedIn →