From b12f0b69e7b7f26a70464fb44193741aa170afe5 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 21 May 2026 12:04:28 +0000 Subject: [PATCH] Sync plugin files from GitHub-Copilot-for-Azure --- .../azure-skills/.claude-plugin/plugin.json | 2 +- .../azure-skills/.cursor-plugin/plugin.json | 2 +- .../plugins/azure-skills/.plugin/plugin.json | 7 +- .github/plugins/azure-skills/CHANGELOG.md | 12 ++ .../skills/azure-diagnostics/SKILL.md | 2 +- .../aks/references/inspektor-gadget.md | 4 +- .../skills/microsoft-foundry/SKILL.md | 2 +- .../foundry-agent/create/create-hosted.md | 6 +- .../create/references/toolbox-reference.md | 102 ++++++++++ .../create/references/toolbox.md | 177 ------------------ .../references/use-toolbox-in-hosted-agent.md | 60 ++++++ .../trace/references/tracing-insights-api.md | 104 ++++++++++ .../foundry-agent/trace/trace.md | 1 + 13 files changed, 294 insertions(+), 187 deletions(-) create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/toolbox-reference.md delete mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/toolbox.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md create mode 100644 .github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/references/tracing-insights-api.md diff --git a/.github/plugins/azure-skills/.claude-plugin/plugin.json b/.github/plugins/azure-skills/.claude-plugin/plugin.json index ef2e4f25..d4d4d725 100644 --- a/.github/plugins/azure-skills/.claude-plugin/plugin.json +++ b/.github/plugins/azure-skills/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "azure", "description": "Microsoft Azure MCP and Skills integration for cloud resource management, deployments, and Azure services. Manage your Azure infrastructure, monitor applications, and deploy resources directly from Claude Code.", - "version": "1.1.44", + "version": "1.1.48", "author": { "name": "Microsoft", "url": "https://www.microsoft.com" diff --git a/.github/plugins/azure-skills/.cursor-plugin/plugin.json b/.github/plugins/azure-skills/.cursor-plugin/plugin.json index 4e91bab9..cc5f6416 100644 --- a/.github/plugins/azure-skills/.cursor-plugin/plugin.json +++ b/.github/plugins/azure-skills/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "azure", "description": "Microsoft Azure MCP and Skills integration for cloud resource management, deployments, and Azure services. Manage your Azure infrastructure, monitor applications, and deploy resources directly from Cursor.", - "version": "1.1.44", + "version": "1.1.48", "author": { "name": "Microsoft", "url": "https://www.microsoft.com" diff --git a/.github/plugins/azure-skills/.plugin/plugin.json b/.github/plugins/azure-skills/.plugin/plugin.json index 98ea414f..03e6065a 100644 --- a/.github/plugins/azure-skills/.plugin/plugin.json +++ b/.github/plugins/azure-skills/.plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "azure", "description": "Microsoft Azure MCP and Skills integration for cloud resource management, deployments, and Azure services. Manage your Azure infrastructure, monitor applications, and deploy resources directly from your development environment.", - "version": "1.1.44", + "version": "1.1.48", "author": { "name": "Microsoft", "url": "https://www.microsoft.com" @@ -21,5 +21,8 @@ ], "skills": "./skills/", "mcpServers": "./.mcp.json", - "hooks": "./hooks/copilot-hooks.json" + "hooks": { + "paths": ["./hooks/copilot-hooks.json"], + "exclusive": true + } } diff --git a/.github/plugins/azure-skills/CHANGELOG.md b/.github/plugins/azure-skills/CHANGELOG.md index 083c03c6..3639957f 100644 --- a/.github/plugins/azure-skills/CHANGELOG.md +++ b/.github/plugins/azure-skills/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## 1.1.47 + +- feat(azure-diagnostics/inspektor-gadget): Use correct filter for tcpdump gadget ([#2292](https://github.com/microsoft/GitHub-Copilot-for-Azure/pull/2292)) + +## 1.1.46 + +- feat(microsoft-foundry): add Tracing Insights API skill for automated anomaly detection ([#2276](https://github.com/microsoft/GitHub-Copilot-for-Azure/pull/2276)) + +## 1.1.45 + +- fix(microsoft-foundry): update integrate toolbox into hosted-agent flow ([#2264](https://github.com/microsoft/GitHub-Copilot-for-Azure/pull/2264)) + ## 1.1.41 - fix: update foundry-agent invoke skill for invocations protocol ([#2154](https://github.com/microsoft/GitHub-Copilot-for-Azure/pull/2154)) diff --git a/.github/plugins/azure-skills/skills/azure-diagnostics/SKILL.md b/.github/plugins/azure-skills/skills/azure-diagnostics/SKILL.md index 7290e5db..69348702 100644 --- a/.github/plugins/azure-skills/skills/azure-diagnostics/SKILL.md +++ b/.github/plugins/azure-skills/skills/azure-diagnostics/SKILL.md @@ -4,7 +4,7 @@ description: "Debug Azure production issues on Azure using AppLens, Azure Monito license: MIT metadata: author: Microsoft - version: "1.1.5" + version: "1.1.6" --- # Azure Diagnostics diff --git a/.github/plugins/azure-skills/skills/azure-diagnostics/troubleshooting/aks/references/inspektor-gadget.md b/.github/plugins/azure-skills/skills/azure-diagnostics/troubleshooting/aks/references/inspektor-gadget.md index 9d96dff3..381a63e0 100644 --- a/.github/plugins/azure-skills/skills/azure-diagnostics/troubleshooting/aks/references/inspektor-gadget.md +++ b/.github/plugins/azure-skills/skills/azure-diagnostics/troubleshooting/aks/references/inspektor-gadget.md @@ -63,11 +63,11 @@ Outputs raw pcap-ng data. Pipe to `tcpdump` for readable output: kubectl debug --profile=sysadmin node/ --attach --quiet \ --image=mcr.microsoft.com/oss/v2/inspektor-gadget/ig: \ -- ig run tcpdump: -o pcap-ng --k8s-namespace --k8s-podname \ - --timeout 30 --filter "port 80" \ + --timeout 30 --pf "port 80" \ | tcpdump -nvr - ``` -Use `--filter ""` for tcpdump filters (e.g., `port 80`, `host 10.0.0.1`). Output must be `-o pcap-ng` (not `-o json`). +Use `--pf ""` for tcpdump filters (e.g., `port 80`, `host 10.0.0.1`). Output must be `-o pcap-ng` (not `-o json`). ### Process & Workload diff --git a/.github/plugins/azure-skills/skills/microsoft-foundry/SKILL.md b/.github/plugins/azure-skills/skills/microsoft-foundry/SKILL.md index 2a1e787c..3b50a8a6 100644 --- a/.github/plugins/azure-skills/skills/microsoft-foundry/SKILL.md +++ b/.github/plugins/azure-skills/skills/microsoft-foundry/SKILL.md @@ -4,7 +4,7 @@ description: "Deploy, evaluate, and manage Foundry agents end-to-end: Docker bui license: MIT metadata: author: Microsoft - version: "1.1.12" + version: "1.1.14" --- # Microsoft Foundry Skill diff --git a/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/create-hosted.md b/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/create-hosted.md index 7c46cd9a..487897d8 100644 --- a/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/create-hosted.md +++ b/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/create-hosted.md @@ -88,7 +88,7 @@ If the user has specified what they want the agent to do, choose the most releva If the requested combination does not have a real sample, say so clearly and suggest the nearest supported lane. -> ⚠️ **Tools:** If the user wants an agent with tools (web search, AI search, code interpreter, MCP servers, etc.), select the `toolbox` samples. These samples include Foundry Toolbox integration in the sample code out of the box, but the user still needs an actual toolbox resource and must configure its endpoint/auth as described in [references/toolbox.md](references/toolbox.md) (see Step 1). +> ⚠️ **Tools:** Hosted agents access tools through a **Foundry Toolbox MCP endpoint** — they do NOT wire tools directly. If the user wants an agent with tools (web search, AI search, code interpreter, MCP servers, etc.), select the `toolbox` samples (see [references/use-toolbox-in-hosted-agent.md#code-integration-patterns](references/use-toolbox-in-hosted-agent.md#code-integration-patterns)). These samples include Foundry Toolbox integration in the sample code out of the box, but the user still needs an actual toolbox resource — you'll resolve its endpoint in Step 6 (Verify Startup). ### Step 4: Download Sample Files @@ -131,6 +131,7 @@ For nested directories, recursively fetch the GitHub contents API for entries wh 1. Install dependencies (use virtual environment for Python) 2. Ask user to provide values for `.env` variables if placeholders were used using `ask_user` tool. + - **If the agent uses tools / toolboxes**: resolve the toolbox endpoint per [references/use-toolbox-in-hosted-agent.md#resolve-toolbox-endpoint](references/use-toolbox-in-hosted-agent.md#resolve-toolbox-endpoint). 3. Run the main entrypoint 4. Fix startup errors and retry if needed 5. Send a protocol-appropriate test request to the correct endpoint: @@ -221,6 +222,7 @@ Modify the project's main entrypoint to wrap the existing agent with the adapter ### Step B4: Configure Environment 1. Create or update a `.env` file with required environment variables (project endpoint, model deployment name, etc.) + - **If the agent uses tools / toolboxes**: resolve the toolbox endpoint per [references/use-toolbox-in-hosted-agent.md#resolve-toolbox-endpoint](references/use-toolbox-in-hosted-agent.md#resolve-toolbox-endpoint). 2. For Python: ensure the code uses `load_dotenv(override=False)` so Foundry-injected environment variables are available at runtime. 3. If the project uses Azure credentials: ensure Python uses `azure.identity.DefaultAzureCredential` for **local development**. In production, use `ManagedIdentityCredential`. See [auth-best-practices.md](../../references/auth-best-practices.md) @@ -277,7 +279,7 @@ Apply these to both greenfield and brownfield projects: 5. **Deploy handoff** — After the agent has been created and local verification succeeds, explicitly tell the user that they can deploy the agent if they want, and ask them to say `deploy agent to foundry` to continue with the deploy sub-skill. -6. **Tool integration** — Hosted agents access tools through [Foundry Toolbox](references/toolbox.md), NOT by wiring tools directly. If the user needs tools (web search, AI search, code execution, MCP servers, etc.), follow the toolbox integration guide. The toolbox provides a single MCP-compatible endpoint that handles credential injection and tool discovery. +6. **Tool integration** — Hosted agents access tools through [Foundry Toolbox](references/use-toolbox-in-hosted-agent.md), NOT by wiring tools directly. If the user needs tools (web search, AI search, code execution, file search, MCP servers, etc.), follow the toolbox integration guide. The toolbox provides a single MCP-compatible endpoint that handles credential injection and tool discovery. 7. **Reserved environment variables** — The Foundry platform injects environment variables into every hosted agent container at startup. You MUST NOT generate, suggest, or configure any of these in `.env` files, `agent.yaml` `environment_variables`, or application code: diff --git a/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/toolbox-reference.md b/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/toolbox-reference.md new file mode 100644 index 00000000..320ca0c2 --- /dev/null +++ b/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/toolbox-reference.md @@ -0,0 +1,102 @@ +# Toolbox Reference + +Endpoint format, MCP protocol details, authentication, OAuth consent handling, endpoint testing, and troubleshooting for Foundry Toolboxes. + +## Endpoint Format + +The toolbox MCP endpoint is constructed from the **project endpoint** + **toolbox name**: + +| Endpoint | URL | +|----------|-----| +| Latest version (default) | `{project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1` | +| Specific version | `{project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1` | + +- **Project endpoint** format: `https://.services.ai.azure.com/api/projects/` +- The latest-version endpoint always serves the toolbox's `default_version`. +- Use the specific-version endpoint to test a version before promoting it. +- **Required header** on every request: `Foundry-Features: Toolboxes=V1Preview` +- `?api-version=v1` query parameter is **required** — requests without it return HTTP 400. + +## MCP Protocol + +Toolboxes use **Model Context Protocol (MCP)** — JSON-RPC 2.0 over HTTP POST: + +- **`initialize`** — Handshake to establish an MCP session. Returns a `mcp-session-id` header to include in subsequent requests. +- **`tools/list`** — Returns all available tools with names, descriptions, and input schemas. +- **`tools/call`** — Invokes a tool with arguments and returns structured results. + +> `prompts/list` is **not supported** by the toolbox endpoint. Always pass `load_prompts=False` to MCP client constructors. + +## Authentication + +- **Agent → Toolbox:** Azure AD bearer token with scope `https://ai.azure.com/.default`, refreshed on every request. +- **Toolbox → External Services:** Managed by the platform via project connections (API keys, OAuth, managed identity). + +## OAuth Consent Handling + +When a toolbox includes an OAuth-based MCP connection (e.g., GitHub OAuth), the first call triggers a `CONSENT_REQUIRED` error (MCP error code `-32006`). The error message contains the consent URL. + +**Agent code must handle this:** +1. Catch MCP error code `-32006` from `tools/call` or during MCP session initialization. +2. Extract the consent URL from the error message. +3. Log the URL and surface it to the user (e.g., print to stdout or return in the agent response). +4. After the user completes the OAuth flow in a browser, retry the call — subsequent calls succeed without re-prompting. + +> This is a one-time flow per user per OAuth connection in a project. The agent should not silently swallow this error. + +## Testing the Toolbox Endpoint + +Before running the full agent, verify the toolbox MCP endpoint works end-to-end. Use `az login` for authentication, then test the three MCP operations in order: + +**1. Get a bearer token:** +```bash +TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv) +TOOLBOX_URL="https://.services.ai.azure.com/api/projects//toolboxes//mcp?api-version=v1" +``` + +**2. Initialize MCP session:** +```bash +curl -sS -X POST "$TOOLBOX_URL" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -H "Foundry-Features: Toolboxes=V1Preview" \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"debug","version":"1.0.0"}}}' \ + -D - | head -20 +``` +Save the `mcp-session-id` header from the response for subsequent calls. + +**3. List tools:** +```bash +curl -sS -X POST "$TOOLBOX_URL" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -H "Foundry-Features: Toolboxes=V1Preview" \ + -H "mcp-session-id: " \ + -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | jq . +``` + +**Checklist:** +- Response contains `result.tools[]` with `len > 0` +- Each tool has `name`, `description`, and `inputSchema` with a `properties` field +- MCP tool names for remote servers are prefixed with `server_label` (e.g., `myserver.get_info`) + +**4. Call a tool (optional):** +```bash +curl -sS -X POST "$TOOLBOX_URL" \ + -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -H "Foundry-Features: Toolboxes=V1Preview" \ + -H "mcp-session-id: " \ + -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"","arguments":{"query":"test"}}}' | jq . +``` + +> For a Python-based debug client, see the `_McpToolboxClient` class in the [BYO toolbox sample `main.py`](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/bring-your-own-toolbox/main.py) — it implements `initialize`, `list_tools`, and `call_tool` using raw `httpx` calls. + +## Troubleshooting + +| Error | Cause | Resolution | +|-------|-------|------------| +| CONSENT_REQUIRED (code -32006) | OAuth MCP connection needs user consent | Open consent URL in browser, complete OAuth flow, retry | +| 401 on MCP calls | Expired token or wrong scope | Use scope `https://ai.azure.com/.default` and refresh token | +| 500 on `prompts/list` | Not supported by toolbox endpoint | Pass `load_prompts=False` to MCP client constructor | +| 500 with non-streaming `tools/call` | Non-streaming not supported | Always use `stream=True` for toolbox MCP tools | diff --git a/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/toolbox.md b/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/toolbox.md deleted file mode 100644 index a68db17c..00000000 --- a/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/toolbox.md +++ /dev/null @@ -1,177 +0,0 @@ -# Foundry Toolbox — Tool Integration for Hosted Agents - -Hosted agents access Foundry-managed tools through a **Toolbox MCP endpoint**. Unlike prompt agents that wire tools directly, hosted agents connect to a single MCP-compatible endpoint that exposes all configured tools. The platform handles credential injection, token refresh, and policy enforcement. - -## Quick Reference - -| Property | Value | -|----------|-------| -| **Toolbox Docs** | https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox | -| **Default Sample (Python)** | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox/maf | -| **Python Hosted Agent — `responses`** | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/responses | -| **Python Hosted Agent — `invocations`** | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/invocations | -| **C# (.NET) Samples** | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/toolbox | -| **Supported Tool Types & Auth** | https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/toolbox/SUPPORTED_TOOLBOX_TOOLS.md | - -## Workflow - -``` -User wants tools in hosted agent - │ - ▼ -Step 1: Does user have a toolbox? - │ ├─ Yes → Step 2 - │ └─ No → Ask, then Step 1b to create one - │ - ▼ -Step 2: Generate agent code with toolbox integration -``` - -After code generation, return to the parent skill's Step 6 (Verify Startup) to run the agent and send a test request. Toolbox auth/connection errors are expected without real Azure credentials — the key validation is that the HTTP server starts and the agent accepts requests. - -### Step 1: Resolve Toolbox - -If the user provides a toolbox name or endpoint URL, or the project already references a toolbox (e.g., in `.env` or `agent.manifest.yaml`) → proceed to Step 2. - -Otherwise, ask: _"Do you have an existing Foundry Toolbox, or should I help create one?"_ Then proceed to Step 1b. - -### Step 1b: Create a Toolbox (if needed) - -**Available tool types:** Web Search, Azure AI Search, Code Interpreter, File Search, MCP Server, OpenAPI, Agent-to-Agent (A2A). For details, see [Configure tools](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox#configure-tools). - -| Method | When to use | References | -|--------|-------------|------------| -| **azd** — preferred | AI can generate `agent.manifest.yaml` and run `azd provision` | [Toolbox docs — azd tab](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox), [`toolbox/azd/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox/azd) (multiple scenario manifests covering tool types + auth patterns) | -| **SDK (Python, .NET, JS)** | AI can generate code to create toolbox programmatically | [Toolbox docs](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox), Python: [`sample_toolboxes_crud.py`](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/toolbox/sample_toolboxes_crud.py), C#: [`csharp/toolbox/crud-sample/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/toolbox/crud-sample) | -| **REST API** | AI can generate HTTP calls | [Toolbox docs — REST API tab](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox) | -| **Foundry Toolkit (VS Code)** — manual | Direct user to create via VS Code extension | [Foundry Toolkit](https://aka.ms/foundrytk), [Tool Catalog](https://code.visualstudio.com/docs/intelligentapps/tool-catalog), [Toolbox docs — VS Code tab](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox) | -| **Foundry Portal** — manual | Direct user to create via portal UI | [Toolbox docs](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox) | - -### Step 2: Generate Agent Code with Toolbox - -The sample repo provides integration patterns for both Python and C#. Read the sample code and adapt it to the user's project. - -**Python samples:** - -| Sample | Framework | Protocol | When to use | -|--------|-----------|----------|-------------| -| [`toolbox/maf/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox/maf) — recommended | Agent Framework (MAF) | Responses | **Default choice** | -| [`bring-your-own/responses/langgraph-toolbox/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/responses/langgraph-toolbox) | LangGraph (BYO) | Responses | LangGraph hosted agent with toolbox | -| [`toolbox/copilot-sdk/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox/copilot-sdk) | GitHub Copilot SDK | Responses | Copilot SDK with toolbox tools | -| [`bring-your-own/responses/bring-your-own-toolbox/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/responses/bring-your-own-toolbox) | Generic MCP (BYO) | Responses | Raw `httpx` MCP client — works with any framework | -| [`bring-your-own/invocations/toolbox/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/invocations/toolbox) | Generic MCP (BYO) | Invocations | Toolbox via Invocations protocol | - -**C# (.NET) samples:** - -| Sample | Description | -|--------|-------------| -| [`csharp/toolbox/maf/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/toolbox/maf) — recommended | Agent Framework agent with toolbox MCP (Responses protocol) | - -**Notes:** (apply to all patterns, both Python and C#): -- Auth: Inject a bearer token with scope `https://ai.azure.com/.default` on every request (Python: `httpx.Auth` subclass; C#: `DefaultAzureCredential` + `BearerTokenAuthenticationPolicy`). -- Header: Always include `Foundry-Features: Toolboxes=V1Preview`. -- MCP client: Pass `load_prompts=False` — the toolbox endpoint does not support `prompts/list`. -- Endpoint: Construct from `{project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1`. - -> 💡 **Tip:** If MCP tools have `require_approval: "always"` in `_meta.tool_configuration`, the agent runtime must ask the user for confirmation before invoking. The toolbox endpoint does not enforce this — your agent code is responsible. - -## Toolbox Reference - -### Endpoint Format - -The toolbox MCP endpoint is constructed from the **project endpoint** + **toolbox name**: - -| Endpoint | URL | -|----------|-----| -| Latest version (default) | `{project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1` | -| Specific version | `{project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1` | - -- **Project endpoint** format: `https://.services.ai.azure.com/api/projects/` -- The latest-version endpoint always serves the toolbox’s `default_version`. -- Use the specific-version endpoint to test a version before promoting it. -- **Required header** on every request: `Foundry-Features: Toolboxes=V1Preview` -- `?api-version=v1` query parameter is **required** — requests without it return HTTP 400. - -### MCP Protocol - -Toolboxes use **Model Context Protocol (MCP)** — JSON-RPC 2.0 over HTTP POST: - -- **`initialize`** — Handshake to establish an MCP session. Returns a `mcp-session-id` header to include in subsequent requests. -- **`tools/list`** — Returns all available tools with names, descriptions, and input schemas. -- **`tools/call`** — Invokes a tool with arguments and returns structured results. - -> `prompts/list` is **not supported** by the toolbox endpoint. Always pass `load_prompts=False` to MCP client constructors. - -### Authentication - -- **Agent → Toolbox:** Azure AD bearer token with scope `https://ai.azure.com/.default`, refreshed on every request. -- **Toolbox → External Services:** Managed by the platform via project connections (API keys, OAuth, managed identity). - -### OAuth Consent Handling - -When a toolbox includes an OAuth-based MCP connection (e.g., GitHub OAuth), the first call triggers a `CONSENT_REQUIRED` error (MCP error code `-32006`). The error message contains the consent URL. - -**Agent code must handle this:** -1. Catch MCP error code `-32006` from `tools/call` or during MCP session initialization. -2. Extract the consent URL from the error message. -3. Log the URL and surface it to the user (e.g., print to stdout or return in the agent response). -4. After the user completes the OAuth flow in a browser, retry the call — subsequent calls succeed without re-prompting. - -> This is a one-time flow per user per OAuth connection in a project. The agent should not silently swallow this error. - -### Testing the Toolbox Endpoint - -Before running the full agent, verify the toolbox MCP endpoint works end-to-end. Use `az login` for authentication, then test the three MCP operations in order: - -**1. Get a bearer token:** -```bash -TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv) -TOOLBOX_URL="https://.services.ai.azure.com/api/projects//toolboxes//mcp?api-version=v1" -``` - -**2. Initialize MCP session:** -```bash -curl -sS -X POST "$TOOLBOX_URL" \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -H "Foundry-Features: Toolboxes=V1Preview" \ - -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"debug","version":"1.0.0"}}}' \ - -D - | head -20 -``` -Save the `mcp-session-id` header from the response for subsequent calls. - -**3. List tools:** -```bash -curl -sS -X POST "$TOOLBOX_URL" \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -H "Foundry-Features: Toolboxes=V1Preview" \ - -H "mcp-session-id: " \ - -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | jq . -``` - -**Checklist:** -- Response contains `result.tools[]` with `len > 0` -- Each tool has `name`, `description`, and `inputSchema` with a `properties` field -- MCP tool names for remote servers are prefixed with `server_label` (e.g., `myserver.get_info`) - -**4. Call a tool (optional):** -```bash -curl -sS -X POST "$TOOLBOX_URL" \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -H "Foundry-Features: Toolboxes=V1Preview" \ - -H "mcp-session-id: " \ - -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"","arguments":{"query":"test"}}}' | jq . -``` - -> For a Python-based debug client, see the `_McpToolboxClient` class in the [BYO toolbox sample `main.py`](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/bring-your-own-toolbox/main.py) — it implements `initialize`, `list_tools`, and `call_tool` using raw `httpx` calls. - -## Troubleshooting - -| Error | Cause | Resolution | -|-------|-------|------------| -| CONSENT_REQUIRED (code -32006) | OAuth MCP connection needs user consent | Open consent URL in browser, complete OAuth flow, retry | -| 401 on MCP calls | Expired token or wrong scope | Use scope `https://ai.azure.com/.default` and refresh token | -| 500 on `prompts/list` | Not supported by toolbox endpoint | Pass `load_prompts=False` to MCP client constructor | -| 500 with non-streaming `tools/call` | Non-streaming not supported | Always use `stream=True` for toolbox MCP tools | diff --git a/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md b/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md new file mode 100644 index 00000000..2daedeae --- /dev/null +++ b/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md @@ -0,0 +1,60 @@ +# Use Toolbox in a Hosted Agent + +Hosted agents access Foundry-managed tools through a **Toolbox MCP endpoint**. Unlike prompt agents that wire tools directly, hosted agents connect to a single MCP-compatible endpoint that exposes all configured tools. The platform handles credential injection, token refresh, and policy enforcement. + +> 📘 For endpoint format, MCP protocol details, auth, OAuth consent handling, testing, and troubleshooting, see [toolbox-reference.md](toolbox-reference.md). + +## Quick Reference + +| Property | Value | +|----------|-------| +| **Toolbox Docs** | https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox | +| **Default Sample (Python)** | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox/maf | +| **Python Hosted Agent — `responses`** | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/responses | +| **Python Hosted Agent — `invocations`** | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/invocations | +| **C# (.NET) Samples** | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/toolbox | +| **Supported Tool Types & Auth** | https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/toolbox/SUPPORTED_TOOLBOX_TOOLS.md | + +## Resolve Toolbox Endpoint + +If the user provides a toolbox name or endpoint URL, or the project already references a toolbox (e.g., in `.env` or `agent.manifest.yaml`) → use it directly. + +Otherwise, ask one question: + +> _"Would you like to provide your toolbox endpoint? (you can create one with the [Foundry Toolkit in VS Code](https://code.visualstudio.com/docs/intelligentapps/tool-catalog) or the [Foundry Portal](https://ai.azure.com/))"_ + +Once the user supplies the toolbox name/endpoint — either an existing one or a new one they create via the Foundry Toolkit or Foundry Portal — set it on the agent (e.g., `FOUNDRY_TOOLBOX_ENDPOINT` in `.env`) and continue with verification. + +> **When asking the question, always include the doc links inline** for the manual options — the [Foundry Toolkit in VS Code](https://code.visualstudio.com/docs/intelligentapps/tool-catalog) and the [Foundry Portal](https://ai.azure.com/) — so the user knows where to go to create a tool/toolbox themselves. Don't just name the options; render them as clickable links every time. + +> **Before printing out any step-by-step guidance** for the Foundry Toolkit (VS Code) path, fetch and read [Use Tool Catalog to connect tools and Toolboxes in Foundry Toolkit](https://code.visualstudio.com/docs/intelligentapps/tool-catalog) first, then summarize the relevant steps for them. Don't paraphrase from memory — the Toolkit UI changes; quote the current doc. + +> **Available tool types** (for context when discussing what the toolbox will contain): Web Search, Azure AI Search, Code Interpreter, File Search, MCP Server (third-party MCP servers, e.g. GitHub, and Microsoft first-party MCP servers, e.g. WorkIQ), OpenAPI, Agent-to-Agent (A2A). See [Configure tools](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox#configure-tools). + +## Code Integration Patterns + +The sample repo provides integration patterns for both Python and C#. Read the sample code and adapt it to the user's project. + +**Python samples:** + +| Sample | Framework | Protocol | When to use | +|--------|-----------|----------|-------------| +| [`toolbox/maf/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox/maf) — recommended | Agent Framework (MAF) | Responses | **Default choice** | +| [`bring-your-own/responses/langgraph-toolbox/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/responses/langgraph-toolbox) | LangGraph (BYO) | Responses | LangGraph hosted agent with toolbox | +| [`toolbox/copilot-sdk/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox/copilot-sdk) | GitHub Copilot SDK | Responses | Copilot SDK with toolbox tools | +| [`bring-your-own/responses/bring-your-own-toolbox/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/responses/bring-your-own-toolbox) | Generic MCP (BYO) | Responses | Raw `httpx` MCP client — works with any framework | +| [`bring-your-own/invocations/toolbox/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/invocations/toolbox) | Generic MCP (BYO) | Invocations | Toolbox via Invocations protocol | + +**C# (.NET) samples:** + +| Sample | Description | +|--------|-------------| +| [`csharp/toolbox/maf/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/toolbox/maf) — recommended | Agent Framework agent with toolbox MCP (Responses protocol) | + +**Notes:** (apply to all patterns, both Python and C#): +- Auth: Inject a bearer token with scope `https://ai.azure.com/.default` on every request (Python: `httpx.Auth` subclass; C#: `DefaultAzureCredential` + `BearerTokenAuthenticationPolicy`). +- Header: Always include `Foundry-Features: Toolboxes=V1Preview`. +- MCP client: Pass `load_prompts=False` — the toolbox endpoint does not support `prompts/list`. +- Endpoint: Construct from `{project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1`. + +> 💡 **Tip:** If MCP tools have `require_approval: "always"` in `_meta.tool_configuration`, the agent runtime must ask the user for confirmation before invoking. The toolbox endpoint does not enforce this — your agent code is responsible. diff --git a/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/references/tracing-insights-api.md b/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/references/tracing-insights-api.md new file mode 100644 index 00000000..1527f2ea --- /dev/null +++ b/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/references/tracing-insights-api.md @@ -0,0 +1,104 @@ +# Tracing Insights API + +Automatically detect quality regressions and anomalies in agent traces using changepoint detection on evaluation scores stored in App Insights. + +## When to Use + +Use this instead of manual KQL queries when you want **automated anomaly detection** across evaluation dimensions (task adherence, intent resolution, fluency, latency, token usage). The API finds statistical changepoints in score distributions — no manual threshold tuning needed. + +**Prerequisites:** +- App Insights connected to the Foundry project (with `gen_ai.evaluation.result` custom events) +- Evaluation data from portal playground sessions or batch evals (raw traces alone are not enough) + +## Endpoint + +``` +POST https://{region}.api.azureml.ms/notification/v1-beta2/subscriptions/{sub}/resourceGroups/{rg}/providers/microsoft.insights/components/{component}/:insights +``` + +The API is region-agnostic — any regional endpoint can serve requests for any project. For lowest latency, use the same region as the Foundry project (e.g., `eastus2`, `westus2`, `westcentralus`). If the project region is unknown, use `eastus2` as the default. + +**Query parameters:** +| Parameter | Required | Description | +|--------------------|----------|------------------------------------------------------------------------| +| `startDateTimeUtc` | Yes | ISO 8601 start of analysis window | +| `endDateTimeUtc` | Yes | ISO 8601 end of analysis window | +| `agent` | Yes | Agent name (URL-encoded) | +| `projectId` | Yes | ARM resource ID of the Foundry project (URL-encoded — contains slashes)| +| `top` | No | Max insights to return (default 50) | + +**Auth:** `az account get-access-token --resource https://ai.azure.com` + +**Body:** Must send `{}` (empty JSON object) — POST with no body returns 400. + +## Example + +```powershell +$token = az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv +$encodedAgent = [uri]::EscapeDataString("my-agent") +$encodedProjectId = [uri]::EscapeDataString("/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}") + +$uri = "https://{region}.api.azureml.ms/notification/v1-beta2/subscriptions/{sub}/resourceGroups/{rg}/providers/microsoft.insights/components/{component}/:insights?startDateTimeUtc=2025-01-01T00:00:00Z&endDateTimeUtc=2025-01-18T00:00:00Z&agent=$encodedAgent&projectId=$encodedProjectId&top=50" + +$response = Invoke-RestMethod -Uri $uri -Method POST -Headers @{ + "Authorization" = "Bearer $token" + "Content-Type" = "application/json" +} -Body "{}" +``` + +## Response Structure (v1-beta2) + +Response is grouped by agent version. Each insight includes `relatedSpans` with `operationId` (App Insights trace ID) for querying full trace content. + +```json +{ + "agents": [{ + "agent": "my-agent:1", + "insights": [{ + "id": "anomaly-token-shift-", + "type": "Token", + "severity": "Critical", + "message": "Token usage increased by 137%", + "agentVersion": "1", + "metadata": { "meanBefore": 2041, "meanAfter": 4831, "confidence": 0.91 }, + "relatedSpans": { + "totalCount": 13, + "spans": [ + { "responseId": "resp_...", "operationId": "", "evaluationRunId": null } + ] + } + }], + "insightCount": 3 + }], + "totalCount": 3, "criticalCount": 1, "warningCount": 1, "improvementCount": 1 +} +``` + +## Querying Traces from relatedSpans + +Use `operationId` from `relatedSpans` to fetch full trace content from App Insights: + +```kql +dependencies +| where operation_Id == "" +| where customDimensions has "invoke_agent" +| project input = customDimensions["gen_ai.input.messages"], + output = customDimensions["gen_ai.output.messages"], + tokens = toint(customDimensions["gen_ai.usage.output_tokens"]) +``` + +This returns the user query and agent response for the specific trace flagged by the insight. + +## How Changepoint Detection Works + +The API finds **statistical inflection points within the queried time window**. `meanBefore`/`meanAfter` represent averages on either side of the detected shift — not comparisons to a historical baseline. + +- 10+ data points give better signal for changepoint detection +- `confidence` close to 1.0 = statistically significant shift + +## Next Steps + +After receiving insights with `Warning` or `Critical` severity: +1. Use `relatedSpans.operationId` values to query full trace content from App Insights (see KQL above) +2. Present the insights summary to the user with severity, type, evaluator name, and shift magnitude +3. Offer to drill into specific traces for detailed analysis using the [trace analysis skill](../trace.md) diff --git a/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/trace.md b/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/trace.md index 0c1a8cd9..c81cd919 100644 --- a/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/trace.md +++ b/.github/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/trace/trace.md @@ -32,6 +32,7 @@ USE FOR: analyze agent traces, search agent conversations, find failing traces, | "Show me this conversation" / "Trace detail" | [Conversation Detail](references/conversation-detail.md) | | "Find eval results for response ID" / "eval scores from traces" | [Eval Correlation](references/eval-correlation.md) | | "What KQL do I need?" | [KQL Templates](references/kql-templates.md) | +| "Auto-detect agent issues" / "Get automated insights" / "What's wrong with my agent?" | [Tracing Insights API](references/tracing-insights-api.md) | ## Before Starting — Resolve App Insights Connection