Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
90dc1c2
Simplify AI Gateway skills and align portable plugin workflows
paulyuk Nov 9, 2026
4e3e7db
Unify skill adapters and correct Waza evaluation contracts
paulyuk Nov 9, 2026
6bbf7ea
Correct Waza planning contracts and bind deny-all tool policy
paulyuk Nov 9, 2026
28612f2
Handle inherent offline preflight warnings without bypassing errors
paulyuk Nov 9, 2026
7f62cda
Supply legitimate planning evidence resources and retain run statuses
paulyuk Nov 9, 2026
d43d1a9
Supply authoritative task context to isolated planning evals
paulyuk Nov 9, 2026
a062f3e
Fail closed before planning eval launch and record evidence limits
paulyuk Nov 9, 2026
2450ba1
Support bounded original-plus-holdout planning trials
paulyuk Nov 9, 2026
517d486
fix: score equivalent planning contracts without weakening scopes
paulyuk Nov 9, 2026
788c9d5
fix: preserve planning semantics and record fail-closed invocations
paulyuk Nov 9, 2026
04e76b2
Accept exact Foundry prerequisite reads in bootstrap evaluation
paulyuk Nov 9, 2026
8f56f69
Record bounded planning results and unresolved approval semantics
paulyuk Nov 9, 2026
ee79110
Separate typed approval operations from explanatory wording
paulyuk Nov 9, 2026
3f9c268
Complete bounded planning corrections and record final evidence
paulyuk Nov 9, 2026
5cac349
Record frozen planning trial and remaining scope contract
paulyuk Nov 9, 2026
7c6b1f4
Clarify single-deployment bootstrap and normalize typed identity case
paulyuk Nov 9, 2026
1558174
Record corrected frozen trials and remaining planning gaps
paulyuk Nov 9, 2026
a2b6624
Require alias family preflight and accept composite counter represent…
paulyuk Nov 9, 2026
08010c6
Apply exact parent preflight reads consistently across planning tasks
paulyuk Nov 9, 2026
157ec44
Fix scoped read comparisons and required gateway preflight
paulyuk Nov 9, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
"name": "aigateway",
"source": "./",
"description": "Create, configure, and operate Azure AI Gateway resources, discover and integrate their models and MCP tools, or migrate supported APIM V2 configuration with local validation and explicit approval.",
"version": "3.0.0",
"version": "4.1.0",
"category": "development",
"keywords": ["ai-gateway", "agents", "mcp", "models", "azure", "integration", "management", "migration"],
"author": {
Expand Down
6 changes: 3 additions & 3 deletions .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
{
"name": "aigateway",
"description": "Create, configure, manage, and build applications on Azure AI Gateway. Includes read-only developer integration and assisted APIM V2 migration with local validation and explicit approval.",
"version": "4.0.0",
"version": "4.1.0",
"keywords": ["ai-gateway", "agents", "mcp", "models", "azure", "integration", "management", "migration"],
"author": {
"name": "Microsoft",
"url": "https://www.microsoft.com"
},
"homepage": "https://github.com/Azure/ai-gateway",
"repository": "https://github.com/Azure/ai-gateway",
"homepage": "https://github.com/Azure/aigateway",
"repository": "https://github.com/Azure/aigateway",
"license": "MIT",
"commands": [
"./commands/discover.md",
Expand Down
2 changes: 1 addition & 1 deletion .cursor-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "aigateway",
"description": "Create, configure, manage, and build applications on Azure AI Gateway. Includes read-only developer integration and assisted APIM V2 migration with local validation and explicit approval.",
"version": "4.0.0",
"version": "4.1.0",
"author": {
"name": "Microsoft",
"url": "https://www.microsoft.com"
Expand Down
14 changes: 14 additions & 0 deletions .github/plugin/marketplace.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"name": "azure",
"owner": {
"name": "Microsoft"
},
"plugins": [
{
"name": "aigateway",
"source": "./",
"description": "Use and administer Azure AI Gateway with native CLI workflows and guarded runtime integration, migration and feedback.",
"version": "4.1.0"
}
]
}
4 changes: 2 additions & 2 deletions .github/plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
{
"name": "aigateway",
"description": "Create, configure, manage, and build applications on Azure AI Gateway. Includes read-only developer integration and assisted APIM V2 migration with local validation and explicit approval.",
"version": "4.0.0",
"version": "4.1.0",
"author": {
"name": "Microsoft",
"url": "https://www.microsoft.com"
},
"repository": "https://github.com/Azure/ai-gateway",
"repository": "https://github.com/Azure/aigateway",
"license": "MIT",
"keywords": ["ai-gateway", "agents", "mcp", "models", "azure", "integration", "management", "migration"],
"commands": [
Expand Down
130 changes: 110 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@
to call model APIs and MCP tools, while
platform teams enforce security, policy, networking, and observability.

- **Govern model APIs** — Microsoft Foundry, OpenAI, Anthropic, Google Vertex, and more, while developers keep the SDKs they already use.
- **Federate MCP tools** — combine MCP servers, OpenAPI APIs, and SaaS connectors behind one governed MCP endpoint.
- **Enforce AI policies** — access, content safety, token, and rate controls, globally or per model and tool.
- **Observe AI traffic** — token usage, latency, errors, and policy outcomes in dashboards and logs.
- **Run on a trusted platform** — the Azure API Management platform, with Private Link, virtual network integration, and managed identity.
- **Govern model APIs:** Microsoft Foundry, OpenAI, Anthropic, Google Vertex, and more, while developers keep the SDKs they already use.
- **Federate MCP tools:** combine MCP servers, OpenAPI APIs, and SaaS connectors behind one governed MCP endpoint.
- **Enforce AI policies:** access, content safety, token, and rate controls, globally or per model and tool.
- **Observe AI traffic:** token usage, latency, errors, and policy outcomes in dashboards and logs.
- **Run on a trusted platform:** the Azure API Management platform, with Private Link, virtual network integration, and managed identity.

> Azure AI Gateway is in **public preview**, available free of charge. See the **[documentation](https://aka.ms/aigateway/docs)** to get started.

Expand All @@ -19,11 +19,13 @@ platform teams enforce security, policy, networking, and observability.

Create and manage gateways, model registrations, MCP servers, and policies with
`az aigateway`. The CLI is an external dependency published in **[Azure/aigateway](https://github.com/Azure/aigateway)**.
See its **[current installation and quickstart](https://github.com/Azure/aigateway/tree/main/cli)** for
See the **[hosted CLI quickstart](https://ai.gateway-df.azure.com/docs/quickstarts/cli)** for
one-line Bash and PowerShell installers, or browse the
[current command reference](https://github.com/Azure/aigateway/blob/main/cli/command-reference.md).
Use the latest published CLI, including preview releases, rather than a local
source build or an installer copied from an older release.
Use the official published CLI, including reviewed preview releases, rather than
a local source build. Ordinary tasks reuse the installed version and task-specific
help; installation/upgrade is separate approved work, not a prerequisite to every
question. Migration retains its stricter release/provenance validation.

## Coding-agent plugin

Expand All @@ -40,28 +42,62 @@ personas:
| Component | Invoked as | Purpose |
| --------- | ---------- | ------- |
| Command `discover` | `/aigateway:discover` | Read-only: list a gateway's models and MCP tool servers and pick the ones that fit your use case. |
| Command `build` | `/aigateway:build` | End-to-end: discover, retrieve a credential, and integrate the models/tools into your app. |
| Command `create` | `/aigateway:create` | Create a gateway and verify that it is ready for configuration. |
| Command `build` | `/aigateway:build` | Integrate supplied or discovered assets using an existing secure credential; selected secret retrieval and live checks require authorization. |
| Command `create` | `/aigateway:create` | Create a gateway; include selected RG/Foundry bootstrap only when explicitly requested and approved. |
| Command `manage` | `/aigateway:manage` | Configure and operate a gateway and its assets. |
| Command `migrate` | `/aigateway:migrate` | Run the assisted, capability-gated APIM V2 migration workflow or resume its verified state. |
| Command `feedback` | `/aigateway:feedback` | Package one selected agent session into a local ZIP for user-controlled sharing; anonymization and review are mandatory for GitHub issues. |
| Skill `use-ai-gateway` | `/aigateway:use-ai-gateway` | Use AI assets from Azure AI Gateway to build intelligent applications. |
| Skill `manage-ai-gateway` | `/aigateway:manage-ai-gateway` | Full administrator workflow for creating, configuring, and operating a gateway. |
| Skill `migrate-ai-gateway` | `/aigateway:migrate-ai-gateway` | Inventory, assess, validate, and reconcile supported APIM V2 configuration to move the workload to Azure AI Gateway. |
| Support utility `feedback-ai-gateway` | `/aigateway:feedback-ai-gateway` | Package one selected session and approved diagnostics for user-controlled support sharing. |

The four public skill names and boundaries are unchanged. Migration remains
bundled; feedback is a support utility, not a prerequisite to gateway work.
All six commands are compatibility adapters into these skills. A skill selects
one authoritative task recipe; adapters do not repeat its instructions or add
mandatory inventories.

### Install

The plugin is hosted in this repository, so your coding agent can install it
directly from Git — no manual file downloads. Pick the tab for your agent:
The root `plugin.json` uses **Agent Plugins 1.0**: the four skills are portable
`skills/<name>/SKILL.md` components. Copilot CLI shortcuts are thin wrappers in
`com.github.copilot/commands/`; Claude/Cursor manifests and Gemini TOML commands
remain available. Shortcut support varies by host; the skills are the shared
workflow, not separate implementations.

Development evaluations and regression tests live in `evals/` and `tests/`,
outside the runtime `skills/` directories. Runtime migration schemas/catalogs
and migration/feedback helpers remain bundled. The portable manifest has no
standard file-exclusion field, so this does not promise that every host omits
development files when downloading the repository.

**GitHub Copilot CLI:** install directly, without registering a marketplace:

```bash
copilot plugin install Azure/aigateway
```

Or use this repository's **azure** marketplace:

```bash
copilot plugin marketplace add Azure/aigateway
copilot plugin install aigateway@azure
```

**VS Code / compatible Copilot products:** use the host's Agent Plugins
installation UI and add this repository's marketplace when supported. In VS
Code, use **Chat: Plugins**; availability depends on the installed version and
organization policy. Do not assume CLI-specific shortcuts load in every product.

**Claude Code / GitHub Copilot CLI** (plugin marketplace protocol):
**Claude Code**:

```
/plugin marketplace add Azure/aigateway
/plugin install aigateway@azure
```

**Cursor** — add this repository as a team marketplace from **Dashboard → Plugins →
**Cursor:** add this repository as a team marketplace from **Dashboard → Plugins →
Add Marketplace → Import from Repo** (`https://github.com/Azure/aigateway`), then
install **aigateway** from **Customize**. For local testing, symlink the repo into
`~/.cursor/plugins/local/aigateway` and reload the window.
Expand All @@ -72,10 +108,14 @@ install **aigateway** from **Customize**. For local testing, symlink the repo in
gemini extensions install https://github.com/Azure/aigateway
```

This layout follows the public awesome-copilot plugin conventions. It does
**not** claim that `aigateway@awesome-copilot` has been accepted or published.
Use the direct repository or `aigateway@azure` installation above.

### Usage

Point the plugin at your gateway's **ARM resource id** (required to list its models and
tools) and describe what you want to build:
For management-enriched discovery, provide the gateway's ARM resource ID and
your use case; listing requires authorized management reads:

```
/aigateway:build /subscriptions/.../aigateways/<gateway> a service that summarizes support tickets
Expand All @@ -87,21 +127,41 @@ Or explore first, then integrate:
/aigateway:discover /subscriptions/.../aigateways/<gateway>
```

For a known endpoint, no ARM ID, subscription inventory or management sign-in
is needed. Supply the exact URL, callable name, operation and existing secure
credential **binding**, never a secret value:

```text
/aigateway:build Integrate https://<published-host>/default/models/openai/v1/chat/completions
using the published alias support/assistant and the existing AI_GATEWAY_API_KEY
binding. The owner verified bearer authentication. Modify my existing Python app;
do not make a live call yet.
```

Published runtime examples differ: the older CLI quickstart uses `Api-Key` and
direct model names, while the hosted quickstart uses bearer authentication and
aliases. The skill preserves the **selected gateway's verified contract**,
not an assumed universal header/model shape or an automatic fallback after 401.

#### Manage

Administrators can create a gateway or manage an existing one:

```
/aigateway:create my-gateway my-resource-group eastus2
/aigateway:manage my-gateway my-resource-group add a Foundry model provider
/aigateway:manage my-gateway my-resource-group register one selected existing Foundry deployment
```

The [administrator skill](skills/manage-ai-gateway/SKILL.md) provides native CLI
runbooks for gateway lifecycle, models and aliases, MCP sources, policies, keys,
identities, networking, and telemetry. It manages only
`Microsoft.ApiManagement/aigateways` and its own children; external resources and
role grants must already be prepared. Routine create/update intent authorizes the
requested work; destructive, access-sensitive, and secret-related operations have
`Microsoft.ApiManagement/aigateways` and its own children. Explicit bootstrap
can create a selected RG and use selected Foundry onboarding after disclosure
and approval of gateway identity and account-level Foundry User grants. Provider
onboarding imports every current deployment; "add one model" is not bulk-import
permission. Other external infrastructure and grants remain prerequisites.
Routine create/update intent authorizes the requested work; destructive,
access-sensitive, and secret-related operations have
specific confirmation gates. [Portal activity coverage and CLI gaps](skills/manage-ai-gateway/references/activities-and-cli-coverage.md)
are explicit rather than bypassed with REST or legacy resource types.

Expand All @@ -113,6 +173,9 @@ Administrators can assess and migrate supported APIM V2 configuration to Azure A
/aigateway:migrate /subscriptions/.../Microsoft.ApiManagement/aigateways/<source-apim>
```

Use the source's actual verified ARM ID and family; do not rewrite a legacy
`Microsoft.ApiManagement/service` ID to `aigateways`.

The assessment inventories AI assets first, then assesses
migrating all discovered AI APIs or a feasible subset.

Expand All @@ -130,6 +193,33 @@ automatically; you choose how to share it. Anonymization is optional for private
sharing. Sharing through a [GitHub issue](https://github.com/Azure/aigateway/issues/new)
requires anonymization, review of the ZIP and issue text, and your explicit approval.

### Scenario coverage and evaluation

The existing skills cover gateway lifecycle, model registration and alias
routing, MCP federation, policy/finops controls, access, networking/private
connections, observability and data-plane integration. They load only the
reference needed for the current task. IaC, backend provisioning and unsupported
native fields remain explicit separate work, not invented CLI operations.

Run deterministic packaging/link/entry-point checks with
`python3 -m unittest discover -s tests`. Migration regressions now run with
`python3 -m unittest discover -s tests/migrate`; feedback regressions run with
`python3 -m unittest discover -s tests/feedback`. On macOS, select a non-symlink
temporary directory through `TMPDIR` for migration tests; their path-safety
checks intentionally reject symlink ancestors. The [evaluation suite](evals/README.md)
defines Waza scenarios and quality/safety criteria for further improvement.
Offline checks do not establish live model quality, cloud behavior or a grade A;
authenticated trials and separately authorized Azure validation are distinct.

### Format references

- [Copilot CLI plugin reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference)
and [shared plugin formats](https://docs.github.com/en/copilot/reference/plugin-and-marketplace-reference).
- [awesome-copilot plugin guide](https://github.com/github/awesome-copilot/blob/main/docs/README.plugins.md)
and [portable Azure exemplar](https://github.com/github/awesome-copilot/blob/main/plugins/azure-cloud-development/plugin.json).
- [CLI b22 release](https://github.com/Azure/aigateway/releases/tag/cli-v1.0.0b22)
and [hosted documentation](https://ai.gateway-df.azure.com/docs/quickstarts/cli).

## Samples

Looking for working examples? The [samples catalog](samples/README.md) curates end-to-end
Expand Down
15 changes: 10 additions & 5 deletions cli/README.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,24 @@
# Azure AI Gateway CLI: external dependency

The CLI is published and maintained through **[Azure/aigateway](https://github.com/Azure/aigateway)**.
This skill repository does not maintain a CLI implementation, local installer,
or copied quickstart.
The plugin uses the released CLI as a dependency; it does not maintain a local
implementation, installer, or copied quickstart.

- [Current installation guide and quickstart](https://github.com/Azure/aigateway/tree/main/cli)
- [Hosted installation guide and CLI quickstart](https://ai.gateway-df.azure.com/docs/quickstarts/cli)
- [Current command reference](https://github.com/Azure/aigateway/blob/main/cli/command-reference.md)
- [Published CLI releases and verified wheel assets](https://github.com/Azure/aigateway/releases)

Use the newest published `cli-v...` release, including public previews. GitHub's
For requested setup/upgrade, resolve the newest published `cli-v...` release,
including public previews. GitHub's
`releases/latest` API omits previews; inspect the releases list instead. Install
the exact official wheel only after verifying its published SHA-256 and obtaining
approval for the tool change. Do not silently substitute an older release.

Check `az aigateway version` and the installed command's `--help`. Do not use
Ordinary management tasks reuse `az aigateway version` for the working context
and inspect only the needed command's `--help`; no recurring release lookup is
required. A complete runtime-only integration needs neither CLI nor management
sign-in. Check the selected gateway's published runtime header/model contract,
not CLI version alone. Do not use
legacy `az ai-gateway` checkouts, local source builds, repacked wheels, or patched
installed modules as the CLI authority. Missing features must be resolved through
the upstream product or reported as unsupported, not invented locally.
Expand Down
6 changes: 6 additions & 0 deletions com.github.copilot/commands/build.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
description: Integrate existing Azure AI Gateway models and MCP tools into an app or a requested standalone agent.
---

Read and follow `commands/build.md` from this plugin's root. Resolve all bundled
paths relative to that root. Apply `$ARGUMENTS` as the user's request.
6 changes: 6 additions & 0 deletions com.github.copilot/commands/create.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
description: Create an Azure AI Gateway, optionally with explicitly requested RG and Foundry bootstrap.
---

Read and follow `commands/create.md` from this plugin's root. Resolve all bundled
paths relative to that root. Apply `$ARGUMENTS` as the user's request.
6 changes: 6 additions & 0 deletions com.github.copilot/commands/discover.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
description: Select authorized Azure AI Gateway models and MCP tools, or explain supplied runtime assets.
---

Read and follow `commands/discover.md` from this plugin's root. Resolve all bundled
paths relative to that root. Apply `$ARGUMENTS` as the user's request.
6 changes: 6 additions & 0 deletions com.github.copilot/commands/feedback.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
description: Package one selected agent session into a local feedback ZIP with reviewed sharing.
---

Read and follow `commands/feedback.md` from this plugin's root. Resolve all bundled
paths relative to that root. Apply `$ARGUMENTS` as the user's request.
6 changes: 6 additions & 0 deletions com.github.copilot/commands/manage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
description: Configure and operate Azure AI Gateway assets, policies, access, networking and telemetry with native CLI commands.
---

Read and follow `commands/manage.md` from this plugin's root. Resolve all bundled
paths relative to that root. Apply `$ARGUMENTS` as the user's request.
6 changes: 6 additions & 0 deletions com.github.copilot/commands/migrate.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
description: Assess and migrate supported APIM V2 configuration with deterministic validation and explicit approval.
---

Read and follow `commands/migrate.md` from this plugin's root. Resolve all bundled
paths relative to that root. Apply `$ARGUMENTS` as the user's request.
Loading