AI setup¶

Deze pagina is voor het platformteam. Ze beschrijft hoe je de AI-agents voor een omgeving inschakelt: het modelendpoint in Azure AI Foundry, de spoke agent (Azure DevOps-repository) en de integration agent (GitHub-repository). Het is een referentieontwerp: jouw deployment kan afwijken.

Wat is nodig¶

Onderdeel	Nodig voor
Azure AI Foundry account met modeldeployments	Alle agents
Configuratie van de spoke agent en repositorypermissies	Spoke agent
Configuratie van de integration agent, GitHub App en repositorypermissies	Integration agent

De agent loop draait in de portalbackend. Foundry wordt gebruikt als modelendpoint (een OpenAI-compatibel endpoint dat de portal met zijn managed identity aanroept). De agents draaien niet in een Foundry agent service. Dit volgt uit het geaccepteerde besluit om over te stappen op een in-process agent loop (Decisions).

Subscription en providers¶

De subscription die Foundry host, heeft deze resource providers geregistreerd nodig: Microsoft.App, Microsoft.ContainerService, Microsoft.CognitiveServices, Microsoft.KeyVault, Microsoft.Network, Microsoft.Search, Microsoft.Storage. De module foundry_platform registreert ook providers via een action.

Moet nog worden geverifieerd

De deploymentrichtlijn noemt alle zeven providers en een gedelegeerd subnet voor AI-agents. De Terraform-module maakt Cosmos DB, AI Search, storage en VNet-injectie alleen aan in bring-your-own-modus (zie hieronder). In de standaardmodus zijn de providers voor search en storage en het gedelegeerde subnet mogelijk niet nodig. Bevestig dit bij de engineer voordat je de klant vraagt ze voor te bereiden.

AI Foundry deployen¶

Voeg de module foundry_platform toe aan elke omgevingsroot en geef het endpoint door aan de module backstage.

module "foundry_platform" {
  source        = "../../modules/foundry_platform"
  location      = module.canvas.location
  environment   = module.canvas.environment
  workload_name = module.canvas.workload_short_name

  add_data_suffix_to_storage_account = false

  ai_user_principal_ids = [
    module.backstage.production_slot_identity_principal_id,
  ]

  spoke_config = {
    owners_group_object_id                   = "<owners-group-object-id>"
    contributors_group_object_id             = "<contributors-group-object-id>"
    vnet_id                                  = module.canvas.virtual_network_id
    snet_pe_id                               = module.canvas.subnets.default.id
    snet_aif_id                              = module.canvas.subnets.<agents-subnet>.id
    log_analytics_workspace_id               = module.canvas.log_analytics_workspace_id
    application_insights_name                = module.azure_monitor.application_insights_name
    application_insights_resource_group_name = module.azure_monitor.application_insights_resource_group_name
  }
}

module "backstage" {
  # ...
  additional_app_settings = {
    services__foundryOpenAIEndpoint__https__0 = "${module.foundry_platform.platform.ai_foundry_openai_endpoint}/openai/v1"
  }
}

Input	Betekenis
`owners_group_object_id`, `contributors_group_object_id`	Entra-groepen die de rollen owner en contributor op het Foundry account krijgen. De meeste landing zones hebben deze groepen al. Vraag anders de Entra-beheerder ze aan te maken.
`ai_user_principal_ids`	Identities die de modellen mogen aanroepen. Geef de identity van het productieslot van de portal mee, die de Foundry user-rol krijgt.
`byo_agent_resources_enabled`	Standaard `false`: Foundry gebruikt zijn door Microsoft gehoste standaard agentbackend ("Basic"). `true` deployt Cosmos DB, AI Search en storage plus VNet-injectie ("Standard").
`foundry_public_access`	Standaard `false`. Er wordt altijd een private endpoint aangemaakt.
`search_sku`	Standaard `basic`, alleen gebruikt met bring-your-own resources

Resources¶

Resource	Aangemaakt
AI Services-account (S0) en project	Altijd
Modeldeployments	Altijd. Standaard `gpt-5.4` en `gpt-5.6-terra`, standard data zone deployment, capaciteit 250.
Private endpoint, Log Analytics workspace, role assignments	Altijd
Cosmos DB, AI Search, storage, hun private endpoints en role assignments	Alleen als `byo_agent_resources_enabled` `true` is

Tegenstrijdige richtlijnen

De oudere deploymentgids en de README van de module noemen Cosmos DB, AI Search, een storage account, een Container App-omgeving en GPT-4o-mini-modellen als altijd aangemaakt. De code van de module komt daar niet mee overeen. Deze pagina volgt de code. Zie Decisions voor de status van de bijbehorende records.

Agentconfiguratie¶

De agents worden ingeschakeld in het app-config.<customer>.yaml van de klant. De agentdefinities (instructies, tools, skills) worden met de code meegeleverd en gerenderd uit templates, dus je stelt alleen de schakelaars en de repository in.

Spoke agent¶

integrations:
  azure:
    - host: dev.azure.com
      useForAI: false   # keep false when the agents use the managed identity for repository access
      credentials:
        - clientId: ${BACKSTAGE_CLIENT_ID}
          clientSecret: ${BACKSTAGE_CLIENT_SECRET}
          tenantId: ${BACKSTAGE_TENANT_ID}

agents:
  spoke:
    enabled: true
    repository:
      organization: '<organisation>'
      projectId: '<project>'
      repositoryId: '<repository>'
      branch: main
      paths:
        spoke: '/<spokes-folder>/'
        spokeSchema: '/<schema-file>.json'
        documentation: ''

Veld	Beschrijving
`organization`, `projectId`, `repositoryId`	Waar de configuratierepository van de spokes staat
`branch`	Branch waaruit wordt gelezen
`paths.spoke`	Map met de spoke-configuratiebestanden
`paths.spokeSchema`	JSON-schema voor validatie
`paths.documentation`	Optioneel
`additionalSchema`, `fileNameRules`	Optioneel extra schema en regels voor bestandsnamen

Permissies in Azure DevOps (uit te voeren door een gebruiker met rechten op organisatieniveau):

Voeg de identity van de portal aan de organisatie toe met toegangsniveau Basic. Zonder deze stap verschijnt de identity niet in de beveiligingsinstellingen van de repository.
Geef die identity Contribute op de spoke-repository.

Zonder Contribute mislukken aanroepen voor branches en pull requests met HTTP 403. De betekenis van de spoke-bestanden staat in de Spoke JSON-referentie en het proces in de Wijzigingsworkflow.

Integration agent¶

De integration agent werkt op een GitHub-repository en authenticeert met een GitHub App.

integrations:
  github:
    - host: <host>
      apiBaseUrl: https://<host>/api/v3
      rawBaseUrl: https://<host>/raw
      apps:
        - appId: ${GITHUB_APP_ID}
          installationId: ${GITHUB_APP_INSTALLATION_ID}
          webhookSecret: 'webhook'      # required by the config, not used
          privateKey: ${GITHUB_APP_PRIVATE_KEY}

agents:
  integration:
    enabled: true
    repository:
      host: '<host>'                    # must equal integrations.github[].host
      owner: '<organisation>'
      repositoryName: '<repository>'
      paths:
        serviceBus:
          schemas: '<schemas-folder>/'
          configuration: '<configuration-folder>/'
          documentation: ''

Met een blok agentsIntegrations.github met dezelfde vorm kun je de agents toegang tot GitHub geven zonder de andere GitHub-features van de portal (zoals TechDocs-scanning) in te schakelen.

Instelling	Bron
`GITHUB_APP_ID`, `GITHUB_APP_INSTALLATION_ID`	Letterlijke app settings in de Terraform root. Ze zijn niet geheim.
`GITHUB_APP_PRIVATE_KEY`	Repository secret dat via `app_secrets` in Key Vault wordt doorgegeven (Configuratie)

Installeer de GitHub App op de doelorganisatie, geef hem toegang tot de integratierepository en verleen Contents: read and write en Pull requests: read and write. Zonder deze rechten mislukken bewerkingen met branches en pull requests met HTTP 403 of 404. Zie Integration platform voor het platform dat deze agent configureert.

Deployen en controleren¶

Deploy via de pipeline (Deployment en omgevingen), eerst test of acceptatie.

Controle	Verwacht
Foundry-resources	Bestaan in de verwachte resource group
Rol	De identity van de portal heeft de Foundry user-rol op het account
Agentconfiguratie	Actief in de draaiende portal (de agent staat op de pagina AI Agents)
Repositorytoegang	De identity heeft Contribute op de spoke-repository
App settings	`GITHUB_APP_*` en het Foundry-endpoint zijn ingesteld op de web app
Spoke agent	Testprompt "List all spoke files" werkt
Integration agent	Testprompt "Show me all existing workloads" werkt
MCP	De toollijst van de MCP-server is niet leeg