> ## Documentation Index > Fetch the complete documentation index at: https://docs.generalvalidation.com/llms.txt > Use this file to discover all available pages before exploring further. # Connect a Microsoft Foundry agent to General Validation > Connect Microsoft Foundry to the General Validation SaaS API with managed identity and the generated agent OpenAPI profile. A Microsoft Foundry agent can inspect validation metadata, propose Tests, and run approved validations through the General Validation SaaS API. Foundry acquires a Microsoft Entra application token for its managed identity and calls the hosted API. General Validation applies the identity's API role and resolves its Organization from the verified Entra directory. Validation compute stays in your Azure environment. Metadata returned to the agent is processed in your Foundry environment; account for that boundary in your organization's Foundry logging and retention settings. ## Before you start You need: * An activated General Validation Organization in the Foundry identity's Entra directory, with a ready execution environment if the agent will run Tests. * A Foundry project, deployed model, and agent you can configure. * A system-assigned managed identity on the parent Foundry resource. * An Entra administrator who can assign the identity a General Validation API application role in your directory. * Network access from Foundry to the General Validation API origin. For the portal OpenAPI integration described here, Microsoft identifies the **parent Foundry resource's system-assigned identity** as the API caller. Record that identity's Object (principal) ID. See Microsoft's [OpenAPI managed-identity setup](https://learn.microsoft.com/en-us/azure/app-service/configure-authentication-ai-foundry-openapi-tool). ## 1. Authorize the managed identity Choose a cumulative role: | Role | Agent workflow | | ------------------- | ------------------------------------------------------------------------ | | `GV.APIReader` | Inspect existing configuration, capabilities, Runs, and result metadata. | | `GV.APIContributor` | Reader access plus permitted Test authoring and validation execution. | | `GV.APIOwner` | Administration explicitly required by an Owner-only operation. | Start with Reader for a read-only assistant, or Contributor to create and run Tests. Follow [API authentication](/api-authentication#set-up-an-api-caller) using the parent Foundry identity's principal ID as `gv_caller_object_id`. Assign the role on the **General Validation API service principal** in your Organization's directory. Azure subscription Contributor is a different permission. The SaaS API registration is separate from the browser application's registration. You do not register a customer-hosted General Validation app or configure App Service authentication to use this integration. ## 2. Retrieve the tool schema and audience Use the General Validation **API origin** and **API client ID** from your Organization's connection configuration or General Validation support. A caller with Reader or higher access can download the generated tool profile: ```bash theme={null} curl --fail-with-body \ --header "Authorization: Bearer ${gv_access_token}" \ "${gv_api_origin}/openapi-agent.json" \ --output general-validation-agent.json ``` Opening that URL in a browser tab alone does not attach a bearer token. The first-party browser sign-in is not a cookie login for API documentation. The deployed canonical `/openapi.json` publishes the client-credentials scope in `components.securitySchemes.entraApplication.x-gv-scope`. Remove its `/.default` suffix to obtain the managed-identity resource URI: ```text theme={null} api:// ``` Use that URI in Foundry's **Audience** field, without `/.default`. The API's client ID is distinct from the browser app client ID. The schema's `servers` entry supplies the API origin. Website-form schemas and repository documents with placeholder hosts are unsuitable for a live connection. `/openapi-agent.json` simplifies request unions for tool clients and includes operation guidance. It is a lossy projection: the canonical `/openapi.json` remains authoritative when validating a request shape. ## 3. Create the OpenAPI tool Open your agent's tools configuration in Microsoft Foundry. Add a custom **OpenAPI tool** and configure these values: | Field | Value | | --------------------- | ------------------------------------------------------------------------------------------- | | Name | `general_validation_api` | | Description | `Inspect validation metadata and create or run approved source-to-target validation tests.` | | Authentication method | **Managed identity** | | Audience | `api://` | | OpenAPI schema | The complete JSON downloaded from the deployed `/openapi-agent.json`. | Save the tool and agent. Foundry supports OpenAPI 3.0 and 3.1 specifications with operation IDs. Its portal labels and supported model combinations can change; use Microsoft's [OpenAPI tool guide](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/openapi) for the current Foundry setup flow. ## 4. Set the agent's operating instructions Use this starting point and adjust it to your review process: ```text theme={null} Use general_validation_api for General Validation requests. Start with read operations. Resolve resource IDs through the API. For a proposed Test, inspect the Pair, its schema, and its authoring capabilities. Use a published function and permitted fields/options. Before a create, update, deactivate, run, cancel, retry, or administrative action, describe the exact proposed change and wait for approval. Never relax a tolerance or invent a business rule. Honor required Idempotency-Key and If-Match headers. Preserve ETag, Location, and Retry-After. Reuse an idempotency key only for an identical retry of the same approved action. Report the final validation outcome separately from HTTP success. A failed check or a Run with no results is not a validation pass. On an API error, report status, code, safe detail, and requestId. Do not echo raw tool wrappers, curl commands, headers, tokens, or debug objects. Do not retry an unchanged invalid request. After a timeout, retain the operation identity and check state before retrying the same idempotent write. Never request customer row evidence, exact values, credentials, or storage access tokens. Do not treat an artifact pointer as permission to fetch the artifact. ``` Instructions help govern intended actions. Entra role assignment remains the hard access boundary: keep an agent on Reader if its job needs only reads. ## 5. Verify with a read-only request Ask the agent: ```text theme={null} Read the General Validation capabilities and report my effective API role. List up to five active Tests. Make no changes. ``` Check the trace for `GET /api/v1/installation/capabilities` and a bounded `GET /api/v1/validation-tests` request to the correct API origin. A successful tool save alone does not prove that authentication or authorization works. After those reads pass, ask the agent to draft a Test against a real Pair. Review the function, fields, filters, join keys, comparison options, tolerances, and evidence settings before approving creation or a Run. ## Troubleshooting | Symptom | Next step | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Schema import fails | Retrieve the complete deployed agent profile and confirm the tool supports the selected model and OpenAPI version. | | `401 Unauthorized` | Verify managed identity authentication, the API resource URI, and the selected identity. Use the API registration's audience without `/.default`. | | `403 Forbidden` | Verify the Foundry identity's API role and that its Entra directory has an activated Organization. Allow new role assignments time to propagate. | | `402 Payment Required` | An Owner should review Organization subscription or trial entitlement and Pair capacity. Retrying does not change billing state. | | `409 Conflict` | Read the returned problem code and resource state. An active Run or missing execution readiness needs resolution before resubmission. | | `412` or `428` | Reread the resource and send its exact strong ETag as `If-Match` after reviewing the current state. | | `422 Unprocessable Entity` | Validate the request against canonical `/openapi.json`, including function-specific required fields. Review any field errors before approving a corrected write. | | `429`, timeout, or `503` | Respect `Retry-After` and use bounded retries. Preserve the operation identity and idempotency key for an uncertain write. | Foundry may wrap an API failure in a tool-level error. Inspect its operation name and HTTP status, then the General Validation problem response when available. Avoid sharing generated curl commands or raw diagnostic wrappers, which can contain authorization headers. Use the [endpoint reference](/api/reference) for each operation's contract and the [error reference](/errors) for remediation. Refresh the tool profile when service contract changes affect your integration.