> For the complete documentation index, see [llms.txt](https://docs.cerrix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cerrix.com/cerrix-documentation-nl/best-practices-en-handleidingen/using-the-cerrix-api-with-ai-assistants-claude-and-microsoft-copilot.md). # De CERRIX-API gebruiken met AI-assistenten (Claude, Microsoft Copilot en ChatGPT) AI-assistenten zoals Claude, Microsoft Copilot en ChatGPT kunnen vragen over uw CERRIX-gegevens beantwoorden in natuurlijke taal — "Welke controles slaagden niet voor hun meest recente effectiviteitstest?", "Vat de incidenten samen die dit kwartaal zijn gemeld" — door rechtstreeks de CERRIX API te bevragen. Deze gids laat vier manieren zien om dat in te stellen, allemaal op basis van standaard CERRIX API-sleutels en zonder extra infrastructuur te hosten. ## Hoe het werkt Moderne AI-assistenten kunnen werken met elke REST API die wordt beschreven door een **OpenAPI-specificatie**. De assistent leest de specificatie om te leren welke eindpunten bestaan, kiest het juiste voor uw vraag, roept de CERRIX API aan met uw API-sleutel (Basic-authenticatie) en formuleert een antwoord op basis van de respons. Deze gids behandelt vier routes: | Assistent | Integratie | Waar het draait | | ------------------------- | --------------------------------------------------------------------------------------- | -------------------- | | **Claude Desktop** | Een lokale toolserver gegenereerd op basis van de OpenAPI-specificatie | Uw eigen werkstation | | **Claude Code** | Directe API-aanroepen vanuit de terminal, begeleid door de specificatie | Uw eigen werkstation | | **Microsoft 365 Copilot** | Een aangepaste connector toegevoegd aan een Copilot Studio-agent | Uw Microsoft-tenant | | **ChatGPT** | De ChatGPT-desktopapp of Codex, met dezelfde lokale toolserver of directe API-aanroepen | Uw eigen werkstation | ## Voordat u begint 1. **Maak een CERRIX API-sleutel aan.** Volg [API-sleutelbeheer en -instelling](/cerrix-documentation-nl/cerrix-functionaliteiten/admin-settings/api-key-management-and-setup.md). 2. **Vraag de CERRIX OpenAPI-specificatie op** via de CERRIX servicedesk. Vraag voor de route met Microsoft Copilot ook om de **Copilot Studio-versie** ; een Swagger 2.0-bestand met een gerichte set alleen-lezenbewerkingen, het formaat dat Power Platform custom connectors vereisen. 3. **Plan uw IP-allowlisting.** API-sleutels zijn beperkt tot toegestane IP-adressen. Voor Claude Desktop, Claude Code en ChatGPT is dat het IP-adres van uw eigen werkstation of (VPN)-netwerk. Voor Microsoft Copilot komen de aanroepen vanuit de cloud van Microsoft — zie de opmerkingen in die sectie. {% hint style="info" %} Voor richtlijnen over welke eindpunten welke vragen beantwoorden — workflow-eindpunten versus de DirectData-rapportagedatasets — zie [API-documentatie](/cerrix-documentation-nl/cerrix-functionaliteiten/admin-settings/api-documentation.md). {% endhint %} ## Optie 1: Claude Desktop Claude Desktop kan lokale toolservers op uw werkstation uitvoeren. Een kant-en-klare open-source tool, de **OpenAPI MCP Server** (gepubliceerd door AWS Labs), zet de CERRIX OpenAPI-specificatie om in tools die Claude kan aanroepen — geen codering vereist, en uw API-gegevens verlaten uw machine nooit, behalve om CERRIX zelf aan te roepen. 1. Installeer de [uv-pakketbeheerder](https://docs.astral.sh/uv/getting-started/installation/) (gebruikt om de toolserver uit te voeren). 2. Sla de CERRIX OpenAPI-specificatie ergens permanent op uw machine op, bijvoorbeeld `Documents/cerrix/cerrix-api-openapi.yaml`. 3. Open in Claude Desktop **Instellingen → Ontwikkelaar → Configuratie bewerken**. Dit opent `claude_desktop_config.json`. Voeg toe: ```json { "mcpServers": { "cerrix": { "command": "uvx", "args": ["awslabs.openapi-mcp-server[yaml]@latest"], "env": { "API_NAME": "cerrix", "API_BASE_URL": "https://[customer short name].cerrix.com/api", "API_SPEC_PATH": "/full/path/to/cerrix-api-openapi.yaml", "AUTH_TYPE": "basic", "AUTH_USERNAME": "", "AUTH_PASSWORD": "", "LOG_LEVEL": "ERROR" } } } } ``` 4. Vervang de basis-URL door uw eigen CERRIX-omgeving, het specificatiepad door de locatie uit stap 2, en de gebruikersnaam en het wachtwoord door de **Identifier** en **Wachtwoord** van uw API-sleutel. 5. Start Claude Desktop opnieuw. De CERRIX-tools verschijnen onder het toolspictogram in de chatinvoer en u kunt vragen gaan stellen. {% hint style="info" %} De CERRIX-API biedt veel eindpunten. Als de tool-lijst lang wordt, ondersteunt de OpenAPI MCP Server het filteren van welke bewerkingen worden weergegeven (bijvoorbeeld met zijn `--include-tags` optie) zodat je het kunt beperken tot de modules die je daadwerkelijk gebruikt. {% endhint %} ## Optie 2: Claude Code Claude Code, Anthropic's agent voor de terminal, heeft helemaal geen extra tooling nodig: geef het de OpenAPI-specificatie en je inloggegevens als omgevingsvariabelen, en het roept de CERRIX API rechtstreeks aan. 1. Installeren [Claude Code](https://code.claude.com/docs/en/overview) en maak een werkmap aan, bijvoorbeeld `cerrix-assistant`, die het CERRIX OpenAPI-specificatiebestand bevat. 2. Maak je API-sleutel beschikbaar als omgevingsvariabelen (bijvoorbeeld in je shellprofiel), zodat de inloggegevens buiten je prompts en bestanden blijven: ```bash export CERRIX_API_USER="" export CERRIX_API_PASSWORD="" ``` 3. Maak in dezelfde map een `CLAUDE.md` bestand dat Claude Code vertelt hoe CERRIX te bereiken: ``` # CERRIX API - Basis-URL: https://[korte naam van de klant].cerrix.com/api - De volledige endpointreferentie staat in cerrix-api-openapi.yaml in deze map. - Authenticatie: HTTP Basic, met behulp van de omgevingsvariabelen CERRIX_API_USER en CERRIX_API_PASSWORD. Voorbeeld: curl -s -u "$CERRIX_API_USER:$CERRIX_API_PASSWORD" \ "https://[korte klantnaam].cerrix.com/api/directdata/v3/risico" - Gebruik de v3-versies van de Risico-eindpunten. - Gebruik alleen GET-eindpunten, tenzij er expliciet wordt gevraagd iets te maken. ``` 4. Start `claude` in die map en stel je vraag. Claude Code zoekt het juiste eindpunt op in de specificatie, voert de API-aanroep uit en kan de resultaten aggregeren, kruislings vergelijken en zelfs in grafieken weergeven. ## Optie 3: Microsoft 365 Copilot (via Copilot Studio) Voor Microsoft Copilot wordt de CERRIX API toegevoegd als een **aangepaste connector voor Power Platform**, die een **Copilot Studio-agent** en gebruikt deze vervolgens als een hulpmiddel. Deze route wordt uitgevoerd binnen uw Microsoft-tenant en kan met uw hele team worden gedeeld via Teams of Microsoft 365 Copilot. 1. Vraag de **Copilot Studio-versie** van de CERRIX-specificatie (Swagger 2.0) via de servicedesk. 2. In het [Power Apps-makerportal](https://make.powerapps.com), selecteer **Oplossingen → Nieuwe oplossing**, voer een weergavenaam in (bijvoorbeeld "CERRIX"), behoud de standaarduitgever en selecteer **Maken**. Copilot Studio kan alleen aangepaste connectors gebruiken die onderdeel zijn van een oplossing, dus maakt u de connector daarin. ![Het deelvenster Nieuwe oplossing in Power Apps met een weergavenaam, naam en uitgever](https://2540748892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEeL4xdXxYZ2fsPsMzsYF%2Fuploads%2Fp0CLnHLBEI1IyXsGN06C%2Fpa-new-solution.png?alt=media) 3. Selecteer in de nieuwe oplossing **Nieuw → Automatisering → Aangepaste connector**. Er wordt een lege connector geopend. Voer bovenaan een naam in (bijvoorbeeld "CERRIX") en schakel **Swagger-editor** en vervang de inhoud van de editor door de volledige inhoud van het specificatiebestand van Copilot Studio. ![Het menu Nieuw in een oplossing, met Automatisering en Aangepaste connector geselecteerd](https://2540748892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEeL4xdXxYZ2fsPsMzsYF%2Fuploads%2FPyj3FZt8hhkSaJ9PkSGD%2Fpa-solution-new-custom-connector.png?alt=media) ![De Swagger-editor met de CERRIX OpenAPI-specificatie erin geplakt en een voorbeeldweergave van de API-bewerkingen](https://2540748892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEeL4xdXxYZ2fsPsMzsYF%2Fuploads%2F3L6ZiDd98kiorZrcLuvz%2Fpa-swagger-editor-v2.webp?alt=media) 4. Schakel uit **Swagger-editor**. Op het **Algemeen** tabblad, stel **Host** in op je eigen CERRIX-omgeving, `[korte klantnaam].cerrix.com`, en controleer of **Base-URL** is `/api`. ![De velden Host en Base-URL op het tabblad Algemeen van de aangepaste connector](https://2540748892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEeL4xdXxYZ2fsPsMzsYF%2Fuploads%2FKGLh815ikYeGrVf1g20m%2Fpa-general-host-base-url.png?alt=media) 5. Op het tabblad **Security** tabblad, kies **Basisverificatie**. Label de velden "API key Identifier" en "API key Password" zodat gebruikers weten wat ze moeten invoeren. Dit zijn alleen weergavelabels: voer hier niet je daadwerkelijke inloggegevens in, omdat elke gebruiker zijn eigen gegevens invoert wanneer die een verbinding maakt. ![Het tabblad Beveiliging met Basisverificatie geselecteerd en de parameternamen API key Identifier en API key Password](https://2540748892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEeL4xdXxYZ2fsPsMzsYF%2Fuploads%2FlRzufveUqpsFfeWzC1tA%2Fpa-security-basic-auth-v2.png?alt=media) 6. Selecteer **Connector maken** bovenaan de pagina om de connector op te slaan. Je moet hem eerst maken voordat je hem kunt testen. 7. Op het tabblad **Test** tabblad, maak een verbinding met de Identifier en het wachtwoord van je API-sleutel en test een bewerking zoals `getDirectdataV3Risk`. De eerste aanroep wordt meestal geblokkeerd door de IP-beperking van de API-sleutel; zie de opmerking over IP-allowlisting hieronder. ![Een geslaagde test van een bewerking op het tabblad Test, met status 200](https://2540748892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEeL4xdXxYZ2fsPsMzsYF%2Fuploads%2Fjq0NiPhZWJqw8cbJeAsL%2Fpa-test-operation.webp?alt=media) 8. In [Copilot Studio](https://copilotstudio.microsoft.com), selecteer **Andere manieren om te bouwen** op de startpagina, en vervolgens **Agent (Standaard)**, en maak de agent. Standaardagenten worden na publicatie in rekening gebracht, dus je kunt bouwen en testen zonder Copilot Credits te gebruiken; de agenttypen met het label **GitHub Copilot** gebruiken vanaf het moment dat je begint met bouwen. ![De startpagina van Copilot Studio met de optie Andere manieren om te bouwen](https://2540748892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEeL4xdXxYZ2fsPsMzsYF%2Fuploads%2FcjOkJ2fAmren8piCoCrL%2Fcs-home-other-ways-to-build.webp?alt=media) ![De optie Agent (Standaard) onder Andere manieren om te bouwen](https://2540748892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEeL4xdXxYZ2fsPsMzsYF%2Fuploads%2F1ioTBdwtrhPhfZcMlINa%2Fcs-agent-standard.webp?alt=media) 9. Op de pagina van de agent, onder **Hulpmiddelen**, selecteer **Tool toevoegen**, kies het **Connector** filter en zoek naar je CERRIX-connector. Selecteer een tool, controleer of **Verbinding** is ingesteld en selecteer **Toevoegen en configureren**. Herhaal dit voor elke tool die je nodig hebt (zie de opmerking hieronder over het kiezen van tools) en laat **Te gebruiken inloggegevens** ingesteld op **inloggegevens van de eindgebruiker**. ![De tools van de CERRIX-connector in het deelvenster Tool toevoegen](https://2540748892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEeL4xdXxYZ2fsPsMzsYF%2Fuploads%2FHXxKWIaRIoqzk9WoeiNM%2Fcs-standard-connector-tools.webp?alt=media) ![Een enkele CERRIX-tool toevoegen met de bijbehorende verbinding, met Toevoegen en configureren](https://2540748892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEeL4xdXxYZ2fsPsMzsYF%2Fuploads%2FZqvHDB12eNeTupj0EDG8%2Fcs-standard-add-and-configure.webp?alt=media) 10. Onder **Instructies**, beschrijf hoe de agent moet werken, bijvoorbeeld: "Beantwoord vragen over onze Risico- en Compliancegegevens in CERRIX. Gebruik altijd de CERRIX-tools en gok nooit. De tools retourneren complete datasets: filter en vat ze zelf samen, en geef aan op hoeveel records uw antwoord is gebaseerd. Deze agent kan alleen gegevens lezen." Onder **Kennis**, schakel web zoeken uit, zodat antwoorden alleen uit CERRIX komen. 11. Open de **Test** deelvenster en stel een vraag. De eerste keer dat de agent een tool gebruikt, vraagt deze u om verbinding te maken met de Identifier en het wachtwoord van uw API-sleutel. ![Het testdeelvenster van Copilot Studio met een antwoord op basis van het Risicoregister van CERRIX](https://2540748892-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEeL4xdXxYZ2fsPsMzsYF%2Fuploads%2FLHpby7G5MH7iKp9r4Gxz%2Fcs-test-answer.png?alt=media) 12. Publiceer de agent. Ga vervolgens op het **Kanalen** tabblad, voeg de **Teams en Microsoft 365 Copilot** kanaal toe, zodat uw team de agent kan gebruiken in Microsoft Teams en Microsoft 365 Copilot. Een paar opmerkingen: * **Kies een gerichte set tools.** Microsoft raadt niet meer dan 25–30 tools per agent aan voor betrouwbare resultaten, en een agent kan er maximaal 128 bevatten. Daarom bevat de Copilot Studio-versie van de specificatie een gerichte set alleen-lezen DirectData-bewerkingen, die modules omvatten zoals Risico, Beheersmaatregel, Incidents, Bevindingenrapport, KRI, Task, Derde partij en Gegevensbeheer. Voeg de tools toe die uw use case nodig heeft. Zie Microsofts [richtlijnen voor generatieve orkestratie](https://learn.microsoft.com/en-us/microsoft-copilot-studio/advanced-generative-actions). * **Copilot-credits.** Na publicatie kunnen gesprekken met de agent Copilot-credits verbruiken, afhankelijk van de Copilot Studio- en Microsoft 365 Copilot-licenties van uw Organisatie. Controleer dit bij uw Microsoft-beheerder voordat u de agent breed uitrolt. * **IP-allowlisting.** Connectorverkeer is afkomstig van Microsofts Power Platform en niet van werkstations van gebruikers, dus de eerste testaanroep wordt meestal geblokkeerd door de IP-beperking van de API-sleutel. Open het profiel van de eigenaar van de sleutel **API** pagina, keur het aanroepadres goed onder **Aangevraagde IP's** en klik op **Opslaan**. Voor een Power Platform-omgeving in Europa is dit een adres zoals `20.86.93.33`. Power Platform kan vanaf elk adres in zijn [gepubliceerde uitgaande bereiken](https://learn.microsoft.com/en-us/connectors/common/outbound-ip-addresses) voor uw regio (voor Europa, de `AzureConnectors.WestEurope` en `AzureConnectors.NorthEurope` servicetags), dus een nieuw adres kan later soms worden geblokkeerd. Keur het op dezelfde manier goed. ## Optie 4: ChatGPT (desktop-app en Codex) de agent van OpenAI **Codex** draait op uw werkstation en is inbegrepen in ChatGPT-abonnementen. De [ChatGPT-desktopapp](https://chatgpt.com/download), de Codex CLI en de Codex IDE-extensie delen één toolconfiguratie, zodat u CERRIX één keer instelt en het vanuit elk daarvan kunt gebruiken. De installatie volgt dezelfde aanpak als de Claude-opties: een lokale toolserver gegenereerd op basis van de OpenAPI-specificatie, of rechtstreekse API-aanroepen vanaf de terminal. **Lokale toolserver (ChatGPT-desktopapp, Codex CLI en IDE-extensie)** 1. Installeer de [uv-pakketbeheerder](https://docs.astral.sh/uv/getting-started/installation/) en sla de CERRIX OpenAPI-specificatie ergens permanent op, zoals in Optie 1. 2. Open het Codex-configuratiebestand `~/.codex/config.toml` (maak het aan als het niet bestaat) en voeg toe: ```toml [mcp_servers.cerrix] command = "uvx" args = ["awslabs.openapi-mcp-server[yaml]@latest"] startup_timeout_sec = 60 [mcp_servers.cerrix.env] API_NAME = "cerrix" API_BASE_URL = "https://[customer short name].cerrix.com/api" API_SPEC_PATH = "/full/path/to/cerrix-api-openapi.yaml" AUTH_TYPE = "basic" AUTH_USERNAME = "" AUTH_PASSWORD = "" LOG_LEVEL = "ERROR" ``` 3. Vervang de basis-URL, het specificatiepad en de inloggegevens zoals beschreven in Optie 1. De langere `startup_timeout_sec` geeft de toolserver tijd om bij de eerste start te downloaden. 4. Start de ChatGPT-desktopapp opnieuw, of start `codex` in een terminal (typ `/mcp` daar om te controleren of de CERRIX-server actief is), en begin vragen te stellen. **Rechtstreekse API-aanroepen (Codex CLI)** De Codex CLI kan de CERRIX-API ook rechtstreeks aanroepen, net als Claude Code. Volg de stappen in Optie 2, maar noem het instructiebestand `AGENTS.md` in plaats van `CLAUDE.md` (Codex leest zijn projectinstructies uit `AGENTS.md`), en start `codex` in die map. Een paar opmerkingen: * **Uw eigen sleutel en IP-adres.** Net als bij de Claude-opties worden aanroepen uitgevoerd vanaf uw eigen werkstation met uw eigen API-sleutel, zodat de gegevenstoegang uw inloggegevens volgt en u uw eigen IP-adres op de allowlist zet. * **Gebruik.** Codex-gebruik telt mee voor de Codex-gebruikslimieten of credits van uw ChatGPT-abonnement. * **De tools beperken.** Om de lijst met tools gefocust te houden, gebruik de `--include-tags` optie (zie Optie 1) of Codex' `enabled_tools` instelling. ## Goede praktijken * **Stem af met uw beveiligings- en privacyfunctionarissen.** Gegevens die door de assistent worden opgehaald, worden verwerkt door de AI-provider (Anthropic, Microsoft of OpenAI) onder de overeenkomsten van uw Organisatie met hen. Bevestig dat de gegevensclassificatie van uw CERRIX-inhoud binnen die overeenkomsten past voordat u dit breed uitrolt. * **Plan de sleutelvernieuwing.** API-sleutels zijn maximaal één jaar geldig, dus plan de vernieuwing en werk de configuratie bij wanneer de sleutel wordt vervangen. ## Vragen om te proberen Zodra u verbonden bent, probeer vragen zoals: * "Welke van onze risico's hebben geen gekoppelde controles?" * "Welke controles zijn gezakt voor hun meest recente effectiviteitstest, en wie is de eigenaar ervan?" * "Vat de incidenten die in het afgelopen kwartaal zijn gemeld samen per classificatie." * "Geef de verbetermaatregelen die te laat zijn, gegroepeerd per onderwerp." --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.cerrix.com/cerrix-documentation-nl/best-practices-en-handleidingen/using-the-cerrix-api-with-ai-assistants-claude-and-microsoft-copilot.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.