Connect a Microsoft Foundry agent to General Validation

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.

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

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:

api://<general-validation-api-client-id>

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://<general-validation-api-client-id>`
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 for the current Foundry setup flow.

4. Set the agent’s operating instructions

Use this starting point and adjust it to your review process:

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:

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 for each operation’s contract and the error reference for remediation. Refresh the tool profile when service contract changes affect your integration.

Using the API

Service capabilities

Discovery

Datasets

Dataset Pairs

Validation Functions

Validation Tests

Runs

Organization

Execution Environment

Billing

Support

Connect a Microsoft Foundry agent to General Validation

Before you start

1. Authorize the managed identity

2. Retrieve the tool schema and audience

3. Create the OpenAPI tool

4. Set the agent’s operating instructions

5. Verify with a read-only request

Troubleshooting

​Before you start

​1. Authorize the managed identity

​2. Retrieve the tool schema and audience

​3. Create the OpenAPI tool

​4. Set the agent’s operating instructions

​5. Verify with a read-only request

​Troubleshooting

Before you start

1. Authorize the managed identity

2. Retrieve the tool schema and audience

3. Create the OpenAPI tool

4. Set the agent’s operating instructions

5. Verify with a read-only request

Troubleshooting