AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

microsoft-foundry

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent, managed harness agent, Copilot harness, voice agent, create/update/invoke/evaluate agent, add tool to agent, agent insights, batch/continuous eval, continuous monitoring, agent CI/CD, optimize/improve prompt, optimize agent instructions, Agent Optimizer, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare).

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read microsoft--microsoft-foundry at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 151

foundry-agent/toolbox/references/tool-openapi.md

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

| Auth | auth object | Connection needed? | |---|---|---| | Anonymous | { type: anonymous } | No | | API key | { type: connection, connection_id: <custom-keys-connection-name> } | Yes — a custom-keys connection whose key name matches the spec's securityScheme name | | Managed identity | { type: managed_identity, audience: <resource-uri> } | No — grant the project MI RBAC on the target, or calls return 401 |


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