canonical: https://jentic.com/apis/azure.com/execution-service

# Microsoft Azure Execution Service

Jentic publishes the only available OpenAPI specification for the Azure Machine Learning Execution Service, keeping it validated and agent-ready. This narrow API starts and cancels training runs against an Azure Machine Learning workspace experiment. It supports starting a remote run, starting a run from a snapshot on a remote compute target, starting a local run, and cancelling a run by run id.

## For AI agents

Start training runs (remote, snapshot, or local) against an Azure ML workspace experiment and cancel a running run by id.

## Scope

Does not register models, manage datasets, provision compute targets, or read run logs and artefacts - use only to start (remote, snapshot, local) and cancel Azure ML training runs.

## Capabilities

- Start a training run on a remote compute target inside an Azure ML workspace experiment
- Start a training run from an existing snapshot on a remote compute target
- Start a training run on the local machine for an experiment
- Cancel a training run by run id within a workspace experiment
- Trigger experiment runs scoped to a specific subscription and resource group

## Use cases

### Trigger Remote Training Runs

Data science teams kick off training jobs on a remote compute cluster from an external orchestrator (CI, scheduler, or agent). POST /execution/v1.0/.../experiments/{experimentName}/startrun submits the run definition to the Azure ML workspace and returns a run id, which the orchestrator stores for later status polling and artefact retrieval against the workspace data plane.

Example prompt: Start a remote run for experiment forecasting-v2 in workspace ml-prod targeting compute aml-cpu-cluster and return the run id

### Snapshot-Based Reproducible Runs

ML platform teams use snapshot runs to rerun a previously captured code and config bundle on different compute, ensuring exact reproducibility across reruns. POST /execution/v1.0/.../experiments/{experimentName}/snapshotrun starts the run from a saved snapshot id so reruns of past experiments do not depend on the current working directory.

Example prompt: Start a snapshot run from snapshot snap-456 for experiment fraud-detect on remote target aml-gpu-cluster

### Cancel a Long-Running Job

Operators cancel a training run that is no longer needed (wrong config, rebased dataset, manual intervention) without waiting for it to fail or time out. POST /execution/v1.0/.../runId/{runId}/cancel signals the orchestrator to stop the run, freeing up compute capacity on the cluster for queued jobs.

Example prompt: Cancel run abc123 in experiment forecasting-v2 in workspace ml-prod and confirm the cancellation was accepted

### Agent-Driven Experiment Orchestration

An AI agent running scheduled retraining can submit, monitor, and cancel runs on Azure ML through Jentic without holding the AAD service principal secret. Intent search returns the four execution endpoints with their schemas; the OAuth token is materialised from your Jentic One instance per call so the agent only ever holds a short-lived bearer.

Example prompt: Search Jentic for 'start an Azure ML training run', execute Runs_StartRun for experiment forecasting-v2, and cancel any older active run on the same experiment

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /execution/v1.0/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.MachineLearningServices/workspaces/{workspaceName}/experiments/{experimentName}/startrun | Start a run on a remote compute target |
| POST | /execution/v1.0/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.MachineLearningServices/workspaces/{workspaceName}/experiments/{experimentName}/snapshotrun | Start a run from a snapshot on a remote compute target |
| POST | /execution/v1.0/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.MachineLearningServices/workspaces/{workspaceName}/experiments/{experimentName}/startlocalrun | Start a run on a local machine |
| POST | /execution/v1.0/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.MachineLearningServices/workspaces/{workspaceName}/experiments/{experimentName}/runId/{runId}/cancel | Cancel an active run |

## Key resources

- **Runs** — Start (remote, snapshot, or local) and cancel training runs scoped to a workspace experiment

## Why Jentic

- **Setup:** Wiring the Azure ML Execution Service by hand means handling Azure AD OAuth 2.0 tokens, building the long Microsoft.MachineLearningServices workspace and experiment path, submitting the run definition, and tracking the run lifecycle from the returned run id. Through Jentic you install once, import the Execution Service from the API Directory, store the Azure AD client credentials once, and your agent calls it.
- **Permission scoping:** The Execution Service puts the subscription, resource group, workspace, and experiment name in the URL path (/execution/v1.0/.../workspaces/{workspaceName}/experiments/{experimentName}/...), so a rule can pin your agent to one workspace experiment. You choose the operations it may call, so limit it to the ones it needs, such as startrun and the run cancel operation, and leave the others out unless you add them.
- **Credential handling:** Your Azure AD client credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time as a scoped bearer token. The service principal secret never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'start an Azure ML training run' or 'cancel a training run', and Jentic returns the matching start, snapshot, local-run, or cancel operation with its input schema so the agent calls the right endpoint without learning the long workspace path.

## Related APIs

- **Azure Machine Learning Workspaces Management** — Provisions and configures the workspaces that this Execution Service submits runs against.
- **Azure Machine Learning Workspaces** — Manages compute targets, datastores, and registered models within an Azure ML workspace.
- **Amazon SageMaker** — AWS managed ML platform with equivalent training-job submission and lifecycle APIs.
- **Google Cloud AI Platform Training** — Google Cloud equivalent for submitting and managing managed training jobs.

## FAQ

### Why is there no official OpenAPI spec for Execution Service?

Microsoft Azure does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Execution Service via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Azure ML Execution Service use?

The API uses Azure Active Directory OAuth 2.0 bearer tokens (the azure_auth scheme). Through Jentic, the AAD service principal secret is stored encrypted in your Jentic One instance and exchanged for a short-lived bearer token per call to the workspace.

### Can I start a training run on Azure ML with this API?

Yes. Call POST /execution/v1.0/.../experiments/{experimentName}/startrun with the run definition to submit a remote run. Use snapshotrun to start from a saved snapshot id, or startlocalrun to run on the local compute. The response returns a run id you can use to track the run.

### How do I cancel a training run that is already in progress?

Send POST /execution/v1.0/.../experiments/{experimentName}/runId/{runId}/cancel with the run id. The orchestrator marks the run for cancellation; you can then poll the workspace data plane to confirm it has reached a terminal state.

### What are the rate limits for the Execution Service?

Azure Machine Learning enforces per-workspace throttling. Submitting many runs in tight loops can return HTTP 429 - back off using the Retry-After header. There is no documented per-endpoint quota in this preview spec; treat the rate as workspace-wide.

### How do I trigger an Azure ML run from an agent through Jentic?

Run pip install jentic, then search Jentic with 'start an Azure ML training run'. Load Runs_StartRun, supply the subscription, resource group, workspace, and experiment names along with the run definition, and execute. The AAD token is sourced from the vault at call time so the agent never sees the service principal secret.

### Can I limit what my agent is allowed to do with the Azure ML Execution Service API?

Yes. Because Jentic One is self-hosted, your own rules decide which operations and credentials the agent may use, and you control what it can call. The Execution Service puts the subscription, resource group, workspace, and experiment name in the URL path, so a rule can pin your agent to a single workspace experiment. You also choose which of the four operations it may run, so you can allow only startrun and the run cancel operation while leaving snapshotrun and startlocalrun out unless you add them.