AI-Setup¶

Diese Seite richtet sich an das Plattform-Team. Sie beschreibt, wie du die AI Agents für eine Umgebung aktivierst: den Modell-Endpoint in Azure AI Foundry, den Spoke-Agent (Azure-DevOps-Repository) und den Integration-Agent (GitHub-Repository). Sie ist ein Referenzdesign: Dein Deployment kann abweichen.

Was gebraucht wird¶

Teil	Gebraucht für
Azure-AI-Foundry-Account mit Modell-Deployments	Alle Agents
Konfiguration des Spoke-Agents und Repository-Berechtigungen	Spoke-Agent
Konfiguration des Integration-Agents, GitHub App und Repository-Berechtigungen	Integration-Agent

Die Agent-Schleife läuft im Portal-Backend. Foundry wird als Modell-Endpoint verwendet (ein OpenAI-kompatibler Endpoint, den das Portal mit seiner Managed Identity aufruft). Die Agents laufen nicht in einem Foundry Agent Service. Das folgt der akzeptierten Entscheidung, auf eine In-Process-Agent-Schleife umzusteigen (Entscheidungen).

Subscription und Provider¶

Die subscription, die Foundry hostet, braucht diese registrierten Resource Provider: Microsoft.App, Microsoft.ContainerService, Microsoft.CognitiveServices, Microsoft.KeyVault, Microsoft.Network, Microsoft.Search, Microsoft.Storage. Das module foundry_platform registriert Provider außerdem über eine Action.

Muss verifiziert werden

Die Liefer-Anleitung nennt alle sieben Provider und ein delegiertes Subnet für AI Agents. Das Terraform-module erstellt Cosmos DB, AI Search, Storage und VNet-Injection nur im Bring-your-own-Modus (siehe unten). Im Standardmodus werden die Provider für Search und Storage sowie das delegierte Subnet möglicherweise nicht gebraucht. Kläre das mit dem Engineer, bevor du den Kunden bittest, sie vorzubereiten.

AI Foundry deployen¶

Füge das module foundry_platform zu jedem Umgebungs-root hinzu und übergib den Endpoint an das 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"
  }
}

Eingabe	Bedeutung
`owners_group_object_id`, `contributors_group_object_id`	Entra-Gruppen, die die Rollen Owner und Contributor auf dem Foundry-Account erhalten. Die meisten landing zones haben diese Gruppen bereits. Bitte sonst den Entra-Administrator, sie anzulegen.
`ai_user_principal_ids`	Identitäten, die die Modelle aufrufen dürfen. Übergib die Identität des Production Slots des Portals, die die Foundry-User-Rolle erhält.
`byo_agent_resources_enabled`	Standard `false`: Foundry verwendet sein von Microsoft gehostetes Standard-Agent-Backend („Basic“). `true` deployt Cosmos DB, AI Search und Storage plus VNet-Injection („Standard“).
`foundry_public_access`	Standard `false`. Ein private endpoint wird immer erstellt.
`search_sku`	Standard `basic`, nur mit Bring-your-own-Ressourcen verwendet

Ressourcen¶

Ressource	Erstellt
AI-Services-Account (S0) und Projekt	Immer
Modell-Deployments	Immer. Standardwerte sind `gpt-5.4` und `gpt-5.6-terra`, Standard-Data-Zone-Deployment, Kapazität 250.
Private endpoint, Log Analytics workspace, Rollenzuweisungen	Immer
Cosmos DB, AI Search, Storage, ihre private endpoints und Rollenzuweisungen	Nur wenn `byo_agent_resources_enabled` auf `true` steht

Widersprüchliche Anleitungen

Die ältere Deployment-Anleitung und die README des modules führen Cosmos DB, AI Search, ein Storage Account, eine Container-App-Umgebung und GPT-4o-mini-Modelle als immer erstellt auf. Der Code des modules stimmt damit nicht überein. Diese Seite folgt dem Code. Den Status der zugehörigen Protokolle siehe Entscheidungen.

Agent-Konfiguration¶

Die Agents werden in der app-config.<customer>.yaml des Kunden aktiviert. Die Agent-Definitionen (Anweisungen, Tools, Skills) werden mit dem Code ausgeliefert und aus Templates gerendert, du setzt also nur die Schalter und das Repository.

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: ''

Feld	Beschreibung
`organization`, `projectId`, `repositoryId`	Wo das Repository mit der spoke-Konfiguration liegt
`branch`	branch, aus dem gelesen wird
`paths.spoke`	Ordner mit den spoke-Konfigurationsdateien
`paths.spokeSchema`	JSON-Schema für die Validierung
`paths.documentation`	Optional
`additionalSchema`, `fileNameRules`	Optionales zusätzliches Schema und optionale Regeln für Dateinamen

Berechtigungen in Azure DevOps (durch einen Benutzer mit Rechten auf Organisationsebene):

Füge die Identität des Portals mit der Zugriffsstufe Basic zur Organisation hinzu. Ohne diesen Schritt erscheint die Identität nicht in den Sicherheitseinstellungen des Repositorys.
Gib dieser Identität auf dem spoke-Repository Contribute.

Ohne Contribute schlagen branch- und Pull-Request-Aufrufe mit HTTP 403 fehl. Die Bedeutung der spoke-Dateien steht in der Spoke-JSON-Referenz und der Prozess im Änderungs-Workflow.

Integration-Agent¶

Der Integration-Agent arbeitet auf einem GitHub-Repository und authentifiziert sich mit einer 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: ''

Ein Block agentsIntegrations.github mit derselben Form erlaubt es, den Agents Zugriff auf GitHub zu geben, ohne die anderen GitHub-Features des Portals (etwa das Scannen für TechDocs) zu aktivieren.

Einstellung	Quelle
`GITHUB_APP_ID`, `GITHUB_APP_INSTALLATION_ID`	Literale App-Einstellungen im Terraform root. Sie sind nicht geheim.
`GITHUB_APP_PRIVATE_KEY`	Repository Secret, über `app_secrets` ins Key Vault gereicht (Konfiguration)

Installiere die GitHub App in der Ziel-Organisation, gib ihr Zugriff auf das Integrations-Repository und erteile Contents: read and write sowie Pull requests: read and write. Ohne diese Rechte schlagen branch- und Pull-Request-Operationen mit HTTP 403 oder 404 fehl. Die Plattform, die dieser Agent konfiguriert, steht in der Integrationsplattform.

Deployen und verifizieren¶

Deploye über die pipeline (Deployment und Umgebungen), zuerst Test oder Acceptance.

Prüfung	Erwartet
Foundry-Ressourcen	Existieren in der erwarteten Resource Group
Rolle	Die Identität des Portals hat die Foundry-User-Rolle auf dem Account
Agent-Konfiguration	Aktiv im laufenden Portal (der Agent erscheint auf der Seite AI Agents)
Repository-Zugriff	Die Identität hat Contribute auf dem spoke-Repository
App-Einstellungen	`GITHUB_APP_*` und der Foundry-Endpoint sind auf der Web App gesetzt
Spoke-Agent	Der Test-Prompt „List all spoke files“ funktioniert
Integration-Agent	Der Test-Prompt „Show me all existing workloads“ funktioniert
MCP	Die Tool-Liste des MCP-Servers ist nicht leer