Connect Microsoft Foundry

Connect Microsoft Foundry

Turn DataMagik scripts and workflows into tools a Microsoft Foundry agent can call, and run DataMagik's own assistant on models you deploy in Azure.

There are two separate ways Microsoft Foundry and DataMagik work together:

• A Foundry agent uses DataMagik — your agent calls DataMagik scripts and workflows through the DataMagik API. Covered first on this page.
• DataMagik uses Foundry — DataMagik's AI Assistant runs on a model deployed in your Azure tenant, through a Microsoft Foundry or Azure OpenAI key added to DataMagik's company keys. See Run the DataMagik assistant on Microsoft Foundry.

For the first, each tool you give the agent is one script or workflow, called with the same endpoint other systems use (see Script Webhooks). You describe those calls in an OpenAPI file, and Foundry's OpenAPI tool lets the agent call them, signed with a DataMagik API key. This gives the agent a small, fixed set of jobs that you built and tested, rather than the whole DataMagik tool set.

Before you start

• A Microsoft Foundry project, and permission to create agents and connections in it.
• The scripts or workflows the agent will call. Each one should do a single job, take a few named inputs, and return small JSON. See Designing scripts for an agent.
• Your DataMagik address (the address you sign in at).

1. Create a DataMagik user and API key for the agent

1. In the Company User Manager, create a user for the agent, such as Foundry Agent. Give it DataMagik - Viewer if its scripts only read data, or DataMagik - Builder if it must run scripts that change data.
2. Sign in as that user, open your profile, then Security Settings.
3. Under Bearer Tokens (API Keys), name the key (for example Foundry – Plant Assistant), choose when it expires, and click Create Bearer Token.
4. Copy the key. It starts with dcp_ and is shown only once.

Why a separate user: the key acts as the user who created it. A dedicated user keeps the agent's runs separate in Executions, limits it to the permissions it needs, and lets you switch it off without affecting a person.

2. Write the OpenAPI file

Describe each script as one operation. Foundry needs an operationId on each operation (letters, - and _ only), plus a securitySchemes section and a security section, or the key is not sent. This example exposes script 482, which looks up a container by serial number:

{
  "openapi": "3.0.3",
  "info": { "title": "DataMagik", "version": "1.0.0" },
  "servers": [ { "url": "https://<your DataMagik address>" } ],
  "paths": {
    "/api/script-engine/scripts/482/execute": {
      "post": {
        "operationId": "get_container_by_serial",
        "summary": "Look up a Plex container by serial number: part, quantity, location and status.",
        "parameters": [
          { "name": "wait", "in": "query", "required": true,
            "schema": { "type": "string", "enum": ["sync"], "default": "sync" } }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": {
            "type": "object",
            "properties": {
              "serial_no": { "type": "string", "description": "Container serial number, e.g. S123456" }
            },
            "required": ["serial_no"]
          } } }
        },
        "responses": { "200": { "description": "The container.",
          "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "datamagikKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
    }
  },
  "security": [ { "datamagikKey": [] } ]
}

• ?wait=sync makes DataMagik hold the call until the script finishes and return the script's return value as the whole response, which is what the agent needs.
• The summary is what the agent reads to decide when to call the tool. Say plainly what it does and returns.
• The request body becomes the script's context. Describe each field so the agent fills it correctly.
• Add one path per script or workflow. A workflow is called the same way, with its ID in the path.

3. Store the key as a Foundry connection

1. In your Foundry project, open Connected resources (or Management center > Connections) and add a new connection of type Custom keys.
2. Add one key: name X-API-Key, value your dcp_ key. The name must match the name in the OpenAPI file's security scheme exactly.
3. Mark the value as secret and save the connection with a clear name, such as datamagik-api.

4. Add the tool to your agent

In the Foundry portal: open your agent, add a tool, choose OpenAPI, paste the OpenAPI file, choose API key / connection authentication and select the datamagik-api connection. Save the agent.

In code (Python, Azure AI Projects SDK), the tool definition references the connection:

import json
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
from azure.identity import DefaultAzureCredential

project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=DefaultAzureCredential())
connection_id = project.connections.get("datamagik-api").id

with open("datamagik_openapi.json") as f:
    spec = json.load(f)

datamagik_tool = {
    "type": "openapi",
    "openapi": {
        "name": "datamagik",
        "description": "Plex data and actions from DataMagik scripts.",
        "spec": spec,
        "auth": {
            "type": "project_connection",
            "security_scheme": {"project_connection_id": connection_id},
        },
    },
}

agent = project.agents.create_version(
    agent_name="plant-assistant",
    definition=PromptAgentDefinition(
        model="gpt-4.1",
        instructions="Answer questions about the plant using the DataMagik tools.",
        tools=[datamagik_tool],
    ),
)

Foundry's SDKs change between versions; check Microsoft's Connect agents to OpenAPI tools article for the current class names.

5. Test

1. Before involving the agent, call the endpoint yourself with the key to confirm the script works:

   curl -X POST 'https://<your DataMagik address>/api/script-engine/scripts/482/execute?wait=sync' \
     -H 'X-API-Key: dcp_your_key' \
     -H 'Content-Type: application/json' \
     -d '{"serial_no": "S123456"}'

2. In the Foundry playground, ask a question that needs the tool, such as "Where is container S123456?"
3. In DataMagik, open Executions and filter Started by to API key (webhook) to see the agent's calls, inputs and results.

Designing scripts for an agent

• One job per script. "Get container by serial" is a better tool than "query Plex".
• Return small, labelled JSON. Return the fields the agent needs with clear names, and cap long lists (for example the top 50 rows). Large responses waste tokens and may be cut off.
• Return a clear message when nothing is found, such as { "found": false, "message": "No container S123456" }, so the agent can say so instead of guessing.
• Keep it fast. A waiting call is held for about 9½ minutes at most, and a company can have 8 waiting calls at once; more come back as 429. Long jobs should run on a schedule and let the agent read the result.
• Be careful with writes. Foundry calls the tool without asking a person first. For anything that writes to Plex, sends email or prints, have the script route the change to Approvals rather than make it directly.
• Group the agent's scripts in an Integration and add the agent's key under Webhook callers to watch its traffic and failures in one place.

Run the DataMagik assistant on Microsoft Foundry (company key)

DataMagik's AI Assistant, AI Agents and other AI features run on an AI provider key that your company supplies. Companies on Azure can keep that traffic in their own Azure tenant, under their own Azure agreement, quotas and content filters, by using one of two cards on the AI Provider Keys page:

Card	Use it when	Endpoint format
Microsoft Foundry	You deploy models in a Foundry resource, including OpenAI models and other models from the Foundry catalog.	https://<resource>.services.ai.azure.com/…
Microsoft OpenAI	You have an Azure OpenAI resource and deploy OpenAI models there.	https://<resource>.openai.azure.com/

Use the matching card. An Azure key does not work on the plain OpenAI card, and a key from the OpenAI platform does not work on the Microsoft cards.

1. Deploy a model and collect its details in Azure

1. In the Foundry portal, open your project (or your Azure OpenAI resource) and deploy a model that supports tool calling, such as a current GPT model. DataMagik's assistant relies on tool calling to reach your data.
2. Note the deployment name. DataMagik calls the deployment by this name, which can differ from the model's name.
3. From the project's Overview page (or, in the Azure portal, the resource's Keys and Endpoint page), copy the endpoint and one of the keys.
4. Check the deployment's tokens-per-minute quota is enough for the people who will use the assistant. A low quota shows up as slow or refused answers at busy times.

2. Add it to DataMagik's company keys

1. In DataMagik, open AI Provider Keys and select the Company Keys tab. This tab needs administrator access.
2. Choose the Microsoft Foundry or Microsoft OpenAI card, to match where you deployed the model.
3. Enter the endpoint, the key and the deployment name the card asks for, and click Save key.
4. Click Set active. The card is marked Active, and everyone without an active personal key now uses your Azure deployment.
5. Open the AI Assistant and ask a question that needs your data, such as "What was scrap yesterday?", to confirm it answers and uses its tools.

• Personal keys win. A user with their own active key under Your Keys uses that key instead of the company key.
• Watch spend in AI Token Usage and in Azure Cost Management.
• Rotating the key: Azure gives each resource two keys. Put the second key on the card and click Replace key, then regenerate the first key in Azure. Nothing stops working in between.
• The same company keys also offer OpenAI, Anthropic Claude, Google Gemini and OpenRouter. See AI Provider Keys.

Troubleshooting

Response or problem	Cause and fix
401 from DataMagik	The key was not sent, is wrong or expired, or its user is inactive. Check the OpenAPI file has both securitySchemes and security, and that the connection key name is exactly X-API-Key.
403	The key's user has neither DataMagik - Builder nor DataMagik - Viewer.
404	The script ID in the path is wrong, the script was deleted, or it belongs to another company.
422	The script ran and failed. Open the run in Executions for the error.
429	Too many waiting calls at once. Retry shortly.
504	The script took longer than the wait allows. It keeps running; make it faster or run it on a schedule.
Foundry will not register the tool	An operationId is missing or uses characters other than letters, - and _.
The DataMagik assistant does not answer on the Azure key	Check the card is Active, the endpoint and key come from the same resource, and the deployment name is spelled exactly as in Azure.
The assistant answers but never looks up data	The deployed model does not support tool calling. Deploy one that does.
Slow or refused answers at busy times	The deployment's quota is too low. Raise it in Azure.

The full list of API responses is in Script Webhooks.