/microsoft-foundry

Tool — OpenAPI (type: openapi)

Expose a REST API to the agent from its OpenAPI 3.x spec. The spec is embedded inline in the toolbox tools: block (under an openapi object) — this is a connectionless built-in, not a connection-backed tool. API-key auth is the one mode that also needs a custom-keys connection. For the toolbox concept, versions, and endpoint, see toolbox.md.

Each operation becomes one tool named {name}___{operationId}, so every operation in the spec needs an operationId (letters, -, _ only).

🚦 Before creating a toolbox/connection either way, read create-hosted.md → Toolbox creation boundary.

Tool entry shape

tools:
  - type: openapi
    openapi:
      name: catfacts            # tool-name prefix: {name}___{operationId}
      spec: { <inline OpenAPI 3.x document> }
      auth: { type: anonymous } # or connection / managed_identity — see below

Auth modes

A. Imperative CLI (anonymous)

Steps 1–3 of toolbox.md § The flow. Write the toolbox spec to a file — azd ai toolbox create --from-file takes a path (stdin - is not supported).

# 0. Install the CLI extension (once)
azd extension install azure.ai.toolboxes

# 1. (API-key auth only) create the custom-keys connection; the key name must match the spec's securityScheme name
azd ai connection create my-api-conn \
  --kind custom-keys --target https://api.example.com \
  --custom-key x-api-key="<api-key>" \
  --project-endpoint "$FOUNDRY_PROJECT_ENDPOINT"

# Write the toolbox spec to a file (anonymous example)
cat > openapi.yaml <<'EOF'
description: openapi toolbox
tools:
  - type: openapi
    openapi:
      name: catfacts
      spec:
        openapi: "3.0.0"
        info: { title: Cat Facts, version: "1.0.0" }
        servers: [{ url: https://catfact.ninja }]
        paths:
          /fact:
            get:
              operationId: getFact
              responses: { "200": { description: ok } }
      auth:
        type: anonymous
EOF

Create a new toolbox (first version auto-promoted):

azd ai toolbox create agent-tools --from-file openapi.yaml --project-endpoint "$FOUNDRY_PROJECT_ENDPOINT"

Add to an existing toolbox: an openapi tool lives in the tools: block, and the azd CLI has no tool add command — only connection add. So you can only create a new toolbox (azd ai toolbox create) with the full tool set, not append an openapi tool to an existing one.

For API-key auth, swap the auth block and add security + securitySchemes to the spec:

tools:
  - type: openapi
    openapi:
      name: my_api
      spec:
        openapi: "3.0.0"
        info: { title: My API, version: "1.0.0" }
        servers: [{ url: https://api.example.com }]
        security: [{ apiKeyHeader: [] }]
        components:
          securitySchemes:
            apiKeyHeader: { type: apiKey, name: x-api-key, in: header }   # name must match the connection key
        paths:
          /thing:
            get: { operationId: getThing, responses: { "200": { description: ok } } }
      auth:
        type: connection
        connection_id: my-api-conn

For managed identity, use auth: { type: managed_identity, audience: https://<resource-uri>/ } and grant the project MI the required RBAC role on the target.

B. Declarative azure.yaml

Declare the toolbox as a host: azure.ai.toolbox service; azd deploy upserts it (and auto-promotes the new version). The openapi tool goes under tools: exactly as in section A.

name: my-agent-project
services:
  agent-tools:
    host: azure.ai.toolbox
    tools:
      - type: openapi
        openapi:
          name: catfacts
          spec:
            openapi: "3.0.0"
            info: { title: Cat Facts, version: "1.0.0" }
            servers: [{ url: https://catfact.ninja }]
            paths:
              /fact:
                get:
                  operationId: getFact
                  responses: { "200": { description: ok } }
          auth:
            type: anonymous

azd deploy agent-tools

Set FOUNDRY_PROJECT_ENDPOINT and AZURE_SUBSCRIPTION_ID in the azd env (after it's created) before azd deploy, or it errors infrastructure has not been provisioned. No azd provision / infra: block is needed. See use-toolbox-in-hosted-agent.md for wiring a hosted agent to the toolbox.

Verify & deploy against Cat Facts

After creating the toolbox either way, verify its MCP endpoint end-to-end (bearer token + raw tools/list / tools/call) — see test-endpoint.md.

With the anonymous Cat Facts spec above: tools/list returns catfacts___getFact; tools/call on it returns a live cat fact ({"fact": "...", "length": ...}).

ENDPOINT=$(azd ai toolbox show agent-tools --project-endpoint "$FOUNDRY_PROJECT_ENDPOINT" --output json \
  | python -c "import sys,json; print(json.load(sys.stdin)['endpoint'])")
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

curl -sS -X POST "$ENDPOINT" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"catfacts___getFact","arguments":{}}}' | python -m json.tool

Multiple openapi entries are allowed in one toolbox only if each spec defines a distinct info.title. See toolbox-azd.md § Multi-tool rule.

References

• OpenAPI tool documentation
• toolbox.md § Supported tool types