Connect your Azure AI Foundry project

A Foundry project connection is how a tenant works with everything its team already built in Azure AI Foundry Agent Service without moving model traffic off Azure. It is project-level (one connection, many agents) and complements the single-agent external agent registration on Connect an external agent — it does not replace it. Positioning: Agentic Workforce ME is the workforce control plane (hierarchy, manifests, human approvals, tenant audit); Foundry stays the Azure-native runtime plane (Entra, Purview, Defender, Monitor). Link = coexist on Azure; import = run on Agentic Workforce ME instead.

1. The four capabilities and their status

2. Quickstart — connect your Foundry project

On the Azure side

Foundry Agent Service needs a kind: AIServices account plus a project, and an Entra app registration that holds the Foundry User role on the project. The platform lists and creates agents, so Foundry Agent Consumer (the invoke-only role that is enough for an external-agent A2A peer) is not enough here. Token scope is https://ai.azure.com/.default.

# 1. A Foundry (kind AIServices) account + project. An Azure OpenAI account is not the same thing.
az cognitiveservices account create -n <account> -g <rg> -l <region> \
  --kind AIServices --sku S0 --custom-domain <account> \
  --assign-identity --allow-project-management true --yes
az cognitiveservices account project create \
  --name <account> --resource-group <rg> --project-name <project> --location <region>

# 2. An Entra app registration for the platform + the "Foundry User" role on the project.
#    (Microsoft renamed "Azure AI User" to "Foundry User" in 2026 — same role id, either label is the same grant.)
az ad app create --display-name awf-foundry-connector      # note appId, then create a client secret
az role assignment create --assignee <appId> \
  --role 53ca6127-db72-4b80-b1b0-d745d6d5456d \
  --scope $(az cognitiveservices account show -n <account> -g <rg> --query id -o tsv)

# Project endpoint — used verbatim as project_endpoint:
#   https://<account>.services.ai.azure.com/api/projects/<project>

Connect, then prove reachability

curl -sS -X POST "https://<api-host>/v1/foundry/connections" \
  -H "Authorization: Bearer hive_…" -H "X-Tenant-Id: <tenant id>" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "gov-project",
    "name": "Foundry — gov (uaenorth)",
    "project_endpoint": "https://<account>.services.ai.azure.com/api/projects/<project>",
    "residency_region": "uaenorth",
    "auth_kind": "entra_client_credentials",
    "credentials": {
      "tenant_id": "<entra tenant id>",
      "client_id": "<app registration client id>",
      "client_secret": "<client secret>"
    }
  }'
# → 201 { connection: { id, slug, …, auth_kind, credential_meta: { tenant_id, client_id } } }
#   credential_meta never carries the secret; no GET route returns it either.

# Token + one inventory call; persists last_inventory and the detected surface.
curl -sS -X POST "https://<api-host>/v1/foundry/connections/<id>/test" \
  -H "Authorization: Bearer hive_…" -H "X-Tenant-Id: <tenant id>"
# → { ok: true, surface: "agents" | "assistants", count: 2 }
# 401 FOUNDRY_AUTH        the Entra token was refused (wrong secret, missing role)
# 502 FOUNDRY_UNREACHABLE the project did not answer

project_endpoint must be https:// and its host must end in .services.ai.azure.com — anything else is 400 VALIDATION before a single byte leaves the platform (the tenant’s Entra bearer is sent to that origin). The credential bag is AES-256-GCM at rest and decrypted only inside the gateway, per call; it is never serialized into prompts, run state, checkpoints, audit rows or logs. PATCH with a new credentials bag rotates it (audited as rotated: true); enabled: false makes every live route answer 409 FOUNDRY_UNREACHABLE.

3. Use it

Understand — inventory and inspect

# Understand: the agents already in the project (GA /agents, classic /assistants fallback; pages of 100, up to 10)
curl -sS "https://<api-host>/v1/foundry/connections/<id>/agents" \
  -H "Authorization: Bearer hive_…" -H "X-Tenant-Id: <tenant id>"
# → { surface, items: FoundryAgentView[] }

# Inspect one: definition, tools, knowledge references, version
curl -sS "https://<api-host>/v1/foundry/connections/<id>/agents/<name>" \
  -H "Authorization: Bearer hive_…" -H "X-Tenant-Id: <tenant id>"
# → { agent: FoundryAgentView }

# Classic surface only — a new-agents-only project answers 409 FOUNDRY_SURFACE_UNSUPPORTED
curl -sS "https://<api-host>/v1/foundry/connections/<id>/agents/<name>/threads" …
curl -sS "https://<api-host>/v1/foundry/connections/<id>/agents/<name>/runs?thread_id=<thread>" …

Integrate — invoke natively, or link as a peer

# Integrate (a): invoke the Foundry agent natively — the run executes in Foundry, on their identity and traces
curl -sS -X POST "https://<api-host>/v1/foundry/connections/<id>/agents/<name>/invoke" \
  -H "Authorization: Bearer hive_…" -H "X-Tenant-Id: <tenant id>" \
  -H "Content-Type: application/json" \
  -d '{ "input": "Screen bid 6003 against bid 6001 for duplicate banking details." }'
# → { result: { text, status: "completed", surface: "agents", remote_response_id, model, usage? } }
#   audit_log foundry.invoke + usage_events external_agent_call (ids, status, latency, token counts — never the text)

# Integrate (b): register the same agent as an external agent (A2A peer) so your agents can call it as a tool / step / delegate
curl -sS -X POST "https://<api-host>/v1/foundry/connections/<id>/agents/<name>/link" \
  -H "Authorization: Bearer hive_…" -H "X-Tenant-Id: <tenant id>" \
  -H "Content-Type: application/json" \
  -d '{ "trust_level": "partner" }'
# → 201 { external_agent: { id, slug, name } }   (provider foundry, protocol a2a-1.0, same encrypted bag)
# 409 FOUNDRY_SURFACE_UNSUPPORTED on an api_key connection — the A2A peer adapter is Entra-only

/invoke is an operator / test path: the raw text comes back to the admin and the run executed in Foundry — its trace lands in their Application Insights; the platform records an audit row and a usage row with the remote ids (correlation, not a second copy of Azure Monitor). Once linked, the Foundry agent is one external agent among the others — tool grants, approval policies, the trust floor and the untrusted-output wrapper all apply, exactly as on Connect an external agent.

Migrate in — import to a draft

# Migrate in (a): from the live project → a DRAFT agent under node_id, HITL defaulted to "review"
curl -sS -X POST "https://<api-host>/v1/foundry/connections/<id>/agents/<name>/import" \
  -H "Authorization: Bearer hive_…" -H "X-Tenant-Id: <tenant id>" \
  -H "Content-Type: application/json" \
  -d '{ "node_id": "<org node id>" }'
# → 201 { agent, version, report: { completeness, unmapped_tools[], knowledge_refs[], suggested_slug, notes[], source } }

# Migrate in (b): offline — paste a classic assistant JSON, a new agent object or an azure.yaml-shaped bundle. No Azure call.
curl -sS -X POST "https://<api-host>/v1/foundry/import-definition" \
  -H "Authorization: Bearer hive_…" -H "X-Tenant-Id: <tenant id>" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "object": "agent.version", "name": "tender-vendor-summary",
      "definition": { "kind": "prompt", "model": "gpt-5-nano",
        "instructions": "You screen tender bids for risk. Never invent a supplier name.",
        "tools": [{ "type": "file_search" }] }
    }
  }'
# → 200 { dry_run: true, view, report, manifest }          (default: nothing is persisted)
# add "persist": true + "node_id" → 201 { agent, version, report }  (a draft, never published)

The fidelity report is the important screen — it never claims a lossless copy:

{
  "completeness": "partial",
  "suggested_slug": "foundry-tender-vendor-summary",
  "unmapped_tools": [
    { "type": "file_search",
      "reason": "Vector store / index stays on Foundry until an explicit KB copy (M3)." },
    { "type": "code_interpreter",
      "reason": "Enable code_execution on the draft after review; not auto-enabled." }
  ],
  "knowledge_refs": [{ "kind": "vector_store", "id": "vs_…" }],
  "notes": ["1 knowledge ref(s) stay on Foundry until an explicit copy."],
  "source": { "surface": "agents", "id": "tender-vendor-summary", "name": "tender-vendor-summary", "kind": "prompt" }
}

completeness is partial whenever a tool did not cross, a knowledge reference exists, or the Foundry kind has no portable prompt (hosted, container_app, workflow, external import as identity only). file_search / azure_ai_search map to the kb.search builtin with the corpus left on Foundry; function, openapi, mcp, azure_function, bing_grounding, a2a / connected_agent are listed with the reason and the suggested rebinding. The draft is an ordinary agent: versioned, publishable, with guardrails and audit.

Publish out — a platform agent on Foundry Agent Service

# Publish out: project a PUBLISHED platform agent onto the project as a Foundry prompt agent. Dry run first.
curl -sS -X POST "https://<api-host>/v1/foundry/connections/<id>/publish" \
  -H "Authorization: Bearer hive_…" -H "X-Tenant-Id: <tenant id>" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "<agent id>", "dry_run": true }'
# → { dry_run: true, hive_version: 3, plan: { method: "POST", path: "/agents", api_version: "v1",
#       body: { name, description?, definition: { kind: "prompt", model, instructions, tools } },
#       omitted: ["mcp:tender-tools (register as a Foundry Toolbox / MCP tool in M2)",
#                 "builtin:kb.search (Foundry file_search needs vector_store_ids; bind a vector store in M3)",
#                 "knowledge_bases[] (no silent corpus copy; bind a Foundry vector store in M3)"] } }

# Then for real (drop dry_run):
# → { result: { remote_id: "tender-drafting-assistant:1", name, version: "1", created: true, model, omitted[] }, plan_omitted[], hive_version }
# Re-publishing the same name: Foundry answers 409 on POST /agents; the platform falls back to POST /agents/{name}/versions,
# which returns the EXISTING version for an identical definition (version: "1", created: false) and mints ":2" only when it changed.
# 404 NOT_FOUND when the agent has no published version (drafts never cross).

Only a published version may cross: published manifests are immutable, so the Foundry projection is reproducible; the platform stays the source of truth and the Foundry agent is a projection of it, never the reverse. omitted[] lists every capability that did not cross — MCP servers, A2A peers, knowledge bases and every builtin, kb.search included: Foundry rejects a bare file_search tool (400 Required property ‘vector_store_ids’ is missing), so nothing is sent for it until M3 binds a vector store. Observed live: Foundry answers POST /agents for an existing name with 409 conflict; the platform then calls POST /agents/{name}/versions, which returns the existing version for an identical definition (created: false, version: "1") and mints a new version only when the definition changed. created is derived from the returned version label. Foundry does not validate the model deployment at create time — a wrong name is accepted and fails only at invoke, so publish agents whose model exists on the project.

4. Reference — routes, shapes, roles

Base path /v1/foundry. Every route needs an API key and X-Tenant-Id (see API keys); rows are tenant-scoped by row-level security, so another tenant’s connection id is a 404. Roles: member may read, admin may write, test, invoke, import, link and publish.

Shapes (from the API’s Zod schemas)

Error codes

5. Governance evidence

6. Not true yet — say it before they ask

• Verified live once (29 Sep 2026) against one GA project: inventory, inspect, invoke, import-to-draft and publish. Not yet observed live: a classic (Assistants-shaped) project, a project that needs the project-scoped Responses fallback (the agent-endpoint route worked with no Foundry-Features header), and hosted / container agents.
• Publish is prompt agents only. Hosted / container publish needs an ACR and agent-identity contract that does not exist. kb.search is omitted on publish until M3 binds a vector store.
• No corpus, Toolbox or eval copy. file_search vector stores stay on Foundry and are referenced; Toolbox → MCP server rows, eval suites and workflow graphs are M3 roadmap — copying classified corpora is an explicit decision, never a side effect.
• No streaming of Foundry tokens; /invoke returns the completed text.
• No traceparent producer on platform runs yet — correlate by the remote ids in usage_events.
• No console card; the public cloud host suffix only (sovereign-cloud suffixes are not allow-listed).

7. What a demo project costs on the Azure side

Microsoft list prices as of 29 Sep 2026. Agent Service charges no per-agent or per-run platform fee for prompt agents — you pay for tokens, metered tools and the optional standard-setup resources.