From a28fe7b2866868755c3223d0d6a5b7fdbefdaf34 Mon Sep 17 00:00:00 2001 From: Xiaofu Huang Date: Thu, 16 Jul 2026 14:26:00 +0800 Subject: [PATCH 1/2] fix(foundry-agent): split prompt-agent tool references into tools/prompt-agent/ Move the 13 per-tool references into references/tools/prompt-agent/ so the prompt-agent (SDK-class) docs live in one folder, ahead of adding a parallel hosted-agent (azd toolbox) set in a follow-up PR. - agent-tools.md: scope to prompt agents; correct SDK class names against azure-ai-projects 2.3.0 (BingGroundingTool, AzureAISearchTool, MemorySearchPreviewTool, WorkIQPreviewTool, FabricIQPreviewTool, ToolSearchToolParam). - tool-a2a.md: add the prompt-agent a2a_preview reference under prompt-agent/; the root references/tool-a2a.md (azd remote-a2a guide from #2846) is left in place and will move to the hosted set in the follow-up PR. - Rewire inbound links in create-prompt.md, foundry-tool-catalog.md, and use-toolbox-in-hosted-agent.md to the new folder. --- .../foundry-agent/create/create-prompt.md | 18 +++---- .../create/references/agent-tools.md | 52 ------------------- .../create/references/foundry-tool-catalog.md | 6 +-- .../create/references/tool-tool-search.md | 2 +- .../tools/prompt-agent/agent-tools.md | 51 ++++++++++++++++++ .../references/tools/prompt-agent/tool-a2a.md | 22 ++++++++ .../prompt-agent}/tool-azure-ai-search.md | 6 +-- .../prompt-agent}/tool-bing-grounding.md | 6 +-- .../prompt-agent}/tool-code-interpreter.md | 2 +- .../prompt-agent}/tool-fabric-iq.md | 2 +- .../prompt-agent}/tool-file-search.md | 0 .../prompt-agent}/tool-function-calling.md | 0 .../{ => tools/prompt-agent}/tool-mcp.md | 6 +-- .../{ => tools/prompt-agent}/tool-memory.md | 2 +- .../{ => tools/prompt-agent}/tool-openapi.md | 4 +- .../prompt-agent}/tool-web-search.md | 0 .../{ => tools/prompt-agent}/tool-work-iq.md | 4 +- .../references/use-toolbox-in-hosted-agent.md | 32 ++++++------ .../references/sdk/foundry-sdk-py.md | 2 +- 19 files changed, 119 insertions(+), 98 deletions(-) delete mode 100644 plugin/skills/microsoft-foundry/foundry-agent/create/references/agent-tools.md create mode 100644 plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/agent-tools.md create mode 100644 plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-a2a.md rename plugin/skills/microsoft-foundry/foundry-agent/create/references/{ => tools/prompt-agent}/tool-azure-ai-search.md (92%) rename plugin/skills/microsoft-foundry/foundry-agent/create/references/{ => tools/prompt-agent}/tool-bing-grounding.md (93%) rename plugin/skills/microsoft-foundry/foundry-agent/create/references/{ => tools/prompt-agent}/tool-code-interpreter.md (91%) rename plugin/skills/microsoft-foundry/foundry-agent/create/references/{ => tools/prompt-agent}/tool-fabric-iq.md (95%) rename plugin/skills/microsoft-foundry/foundry-agent/create/references/{ => tools/prompt-agent}/tool-file-search.md (100%) rename plugin/skills/microsoft-foundry/foundry-agent/create/references/{ => tools/prompt-agent}/tool-function-calling.md (100%) rename plugin/skills/microsoft-foundry/foundry-agent/create/references/{ => tools/prompt-agent}/tool-mcp.md (91%) rename plugin/skills/microsoft-foundry/foundry-agent/create/references/{ => tools/prompt-agent}/tool-memory.md (99%) rename plugin/skills/microsoft-foundry/foundry-agent/create/references/{ => tools/prompt-agent}/tool-openapi.md (87%) rename plugin/skills/microsoft-foundry/foundry-agent/create/references/{ => tools/prompt-agent}/tool-web-search.md (100%) rename plugin/skills/microsoft-foundry/foundry-agent/create/references/{ => tools/prompt-agent}/tool-work-iq.md (86%) diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/create-prompt.md b/plugin/skills/microsoft-foundry/foundry-agent/create/create-prompt.md index f1b0a336e..b6657fb83 100644 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/create-prompt.md +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/create-prompt.md @@ -57,7 +57,7 @@ For a **workflow**: If MCP tools are unavailable, use the `azure-ai-projects` SDK: - See [SDK Operations](references/sdk-operations.md) for create, list, update, delete code samples -- See [Agent Tools](references/agent-tools.md) for adding tools to agents +- See [Agent Tools](references/tools/prompt-agent/agent-tools.md) for adding tools to agents ### Step 4: Add Tools (Optional) @@ -65,16 +65,16 @@ If MCP tools are unavailable, use the `azure-ai-projects` SDK: | Tool Category | Reference | |---------------|-----------| -| Code Interpreter, Function Calling | [Simple Tools](references/agent-tools.md) | -| File Search (requires vector store) | [File Search](references/tool-file-search.md) | -| Web Search (default, no setup needed) | [Web Search](references/tool-web-search.md) | -| Bing Grounding (explicit request only) | [Bing Grounding](references/tool-bing-grounding.md) | -| Azure AI Search (private data) | [Azure AI Search](references/tool-azure-ai-search.md) | -| MCP Servers | [MCP Tool](references/tool-mcp.md) | -| Memory (persistent across sessions) | [Memory](references/tool-memory.md) | +| Code Interpreter, Function Calling | [Simple Tools](references/tools/prompt-agent/agent-tools.md) | +| File Search (requires vector store) | [File Search](references/tools/prompt-agent/tool-file-search.md) | +| Web Search (default, no setup needed) | [Web Search](references/tools/prompt-agent/tool-web-search.md) | +| Bing Grounding (explicit request only) | [Bing Grounding](references/tools/prompt-agent/tool-bing-grounding.md) | +| Azure AI Search (private data) | [Azure AI Search](references/tools/prompt-agent/tool-azure-ai-search.md) | +| MCP Servers | [MCP Tool](references/tools/prompt-agent/tool-mcp.md) | +| Memory (persistent across sessions) | [Memory](references/tools/prompt-agent/tool-memory.md) | | Connections (for tools that need them) | [Project Connections](../../project/connections.md) | -> ⚠️ **Web Search Default:** Use `WebSearchPreviewTool` for web search. Only use `BingGroundingAgentTool` when the user explicitly requests Bing Grounding. +> ⚠️ **Web Search Default:** Use `WebSearchPreviewTool` for web search. Only use `BingGroundingTool` when the user explicitly requests Bing Grounding. ## Error Handling diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/agent-tools.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/agent-tools.md deleted file mode 100644 index 9924f4eb0..000000000 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/references/agent-tools.md +++ /dev/null @@ -1,52 +0,0 @@ -# Agent Tools - -This file is the **index** for every tool an agent can use. For each tool, it points to a dedicated reference file, and — where the tool is also available through a [toolbox](use-toolbox-in-hosted-agent.md) — lists the toolbox `type` value. - -Two delivery paths exist: - -- **Prompt agent** — the agent definition declares tool classes directly (`CodeInterpreterTool`, `MCPTool`, …). Use the SDK class column and the per-tool reference. -- **Hosted agent via toolbox** — the agent connects to a single MCP endpoint that exposes all tools declared in a toolbox version. Use the `type` column and see [use-toolbox-in-hosted-agent.md](use-toolbox-in-hosted-agent.md). For wiring the underlying project connection (catalog tile or generic remote MCP), see [foundry-tool-catalog.md](foundry-tool-catalog.md). - -> 💡 **Authoritative tool shapes:** the source-of-truth for every tool's wire shape is the **Foundry Agents typespec** on the `main` branch of [`Azure/azure-rest-api-specs`](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/cognitiveservices). When in doubt about a field name, default, or new tool type that isn't yet documented here, load the typespec directly — it's updated as tools are added/changed. - -## Tool Summary - -| Tool | Prompt-agent SDK class | Toolbox `type` | Connection? | Reference | -|------|------------------------|----------------|-------------|-----------| -| Code Interpreter | `CodeInterpreterTool` | `code_interpreter` | No | [tool-code-interpreter.md](tool-code-interpreter.md) | -| Function calling (client-side) | `FunctionTool` | — (client-side only) | No | [tool-function-calling.md](tool-function-calling.md) | -| File Search | `FileSearchTool` | `file_search` | No (vector store required) | [tool-file-search.md](tool-file-search.md) | -| Web Search (preview) | `WebSearchPreviewTool` | `web_search` (with optional `web_search.custom_search_configuration` for Bing Custom Search) | No (basic Bing); **Yes** for Grounding with Bing Custom Search — the connection scopes grounding to specific domains | [tool-web-search.md](tool-web-search.md) | -| Bing Grounding | `BingGroundingAgentTool` | — (N/A in toolbox; the toolbox path uses `web_search` with `web_search.custom_search_configuration`) | Yes (Bing) — prompt-agent path only | [tool-bing-grounding.md](tool-bing-grounding.md) | -| Azure AI Search | `AzureAISearchAgentTool` | `azure_ai_search` | Yes (Search) | [tool-azure-ai-search.md](tool-azure-ai-search.md) | -| MCP server (remote) | `MCPTool` | `mcp` | Optional (none / static key / project MI / OAuth) | [tool-mcp.md](tool-mcp.md); toolbox attach via [foundry-tool-catalog.md](foundry-tool-catalog.md) | -| OpenAPI tool | (n/a as a single class) | `openapi` | Conditional — `connection` auth requires `project_connection_id`; **`managed_identity` auth does NOT** (the project MI is used directly with an `audience`) | [tool-openapi.md](tool-openapi.md) | -| Agent-to-Agent (A2A) | (n/a as a single class) | `a2a_preview` | Optional | [tool-a2a.md](tool-a2a.md) | -| Agent Memory | `MemorySearchTool` | — (separate memory store) | Yes (project MI + embedding model) | [tool-memory.md](tool-memory.md) | -| **Work IQ (preview)** | (n/a — server-side only) | `work_iq_preview` | Yes (Work IQ BYO-Entra-app OAuth connection) | [tool-work-iq.md](tool-work-iq.md) | -| **Fabric IQ (preview)** | (n/a — server-side only) | `fabric_iq_preview` | Yes (Fabric IQ Entra-app OAuth or managed-OAuth connection) | [tool-fabric-iq.md](tool-fabric-iq.md) | -| **Tool Search (preview)** | (n/a — toolbox-side configuration directive) | `toolbox_search_preview` | No | [tool-tool-search.md](tool-tool-search.md) | - -> ⚠️ **Default for web search:** Use `WebSearchPreviewTool` (`type: web_search`) unless the user explicitly requests Bing Grounding or Bing Custom Search. - -> Combine multiple tools on one agent or one toolbox version. The model decides which to invoke. For multi-tool toolbox limits (at most one unnamed tool per type, unique `server_label` per MCP tool) see [toolbox-reference.md](toolbox-reference.md#multi-tool-toolbox-constraint). - -## How to use this index - -When you need details for a specific tool, **load that tool's reference file directly** — each one is self-contained (shape, requirements, references). Don't try to keep all tools in context at once. - -For the toolbox runtime contract (endpoint, auth, MCP protocol, citation patterns, troubleshooting) see [toolbox-reference.md](toolbox-reference.md). For wiring a toolbox into a hosted agent (env vars, samples, tracing) see [use-toolbox-in-hosted-agent.md](use-toolbox-in-hosted-agent.md). - -## Adjacent (not a `type` in a toolbox version) - -- **Agent Memory** — use the `MemorySearchTool` SDK class on prompt agents; for hosted agents, configure the memory store via the project (separate from the toolbox). See [tool-memory.md](tool-memory.md). -- **Routines (preview)** — not a tool; an agent **trigger** (`schedule` / `timer` / `github_issue` / `custom`) that invokes an existing agent. Event-based routines are powered by the same **Connector Namespace** that backs catalog-MCP / managed-MCP connectors. See the [public Routines docs](https://learn.microsoft.com/azure/foundry/agents/how-to/use-routines). - -## References - -- **[Foundry Agents typespec (`main`)](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/cognitiveservices)** — authoritative tool shapes -- [Tool Catalog](https://learn.microsoft.com/azure/foundry/agents/concepts/tool-catalog) -- [Toolbox (preview)](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox) -- [use-toolbox-in-hosted-agent.md](use-toolbox-in-hosted-agent.md) — wiring a toolbox into a hosted agent -- [toolbox-reference.md](toolbox-reference.md) — toolbox runtime contract -- [foundry-tool-catalog.md](foundry-tool-catalog.md) — project connections for remote tools diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/foundry-tool-catalog.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/foundry-tool-catalog.md index d39e00692..1648bc31c 100644 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/references/foundry-tool-catalog.md +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/foundry-tool-catalog.md @@ -7,7 +7,7 @@ Reference for wiring a **remote tool** (catalog tile or generic MCP server) into Three catalog backends cooperate: the **asset-gallery** index discovers connectors, the Logic Apps **managedApis** GET supplies OAuth metadata, and the Logic Apps **apiOperations** GET supplies the operation list and input schemas. Skip these calls only for fully BYO `generic_mcp` servers — every catalog-MCP or connector-namespace flow needs all three. > 📘 For the toolbox MCP endpoint, protocol, and testing, see [toolbox-reference.md](toolbox-reference.md). -> 📘 For prompt-agent MCP wiring (without a toolbox), see [tool-mcp.md](tool-mcp.md). +> 📘 For prompt-agent MCP wiring (without a toolbox), see [tool-mcp.md](tools/prompt-agent/tool-mcp.md). ## When to use this reference @@ -703,7 +703,7 @@ The response body for `/mcp` is plain JSON (no SSE `data:` framing) despite the - [Toolbox (preview)](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox) - [Private tools catalog](https://learn.microsoft.com/azure/foundry/agents/concepts/tool-catalog#private-tools-catalog) - [Cognitive Services projects REST API](https://learn.microsoft.com/rest/api/aiservices/) -- [tool-mcp.md](tool-mcp.md) — prompt-agent MCP wiring (no toolbox) +- [tool-mcp.md](tools/prompt-agent/tool-mcp.md) — prompt-agent MCP wiring (no toolbox) - [toolbox-reference.md](toolbox-reference.md) — MCP endpoint, auth, testing, troubleshooting -- [agent-tools.md](agent-tools.md) — the agent-tools index +- [agent-tools.md](tools/prompt-agent/agent-tools.md) — the agent-tools index - [use-toolbox-in-hosted-agent.md](use-toolbox-in-hosted-agent.md) — wiring a toolbox into a hosted agent diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-tool-search.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-tool-search.md index b40d0cea2..e2aebbf73 100644 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-tool-search.md +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-tool-search.md @@ -35,5 +35,5 @@ For toolboxes containing many tools, replace the full tool list passed to the mo For full fields, pinning recipes, the verify-with-`tool_search` flow, and best practices, see [Tool Search tool documentation](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/tool-search). -- [agent-tools.md](agent-tools.md) — tool index +- [agent-tools.md](tools/prompt-agent/agent-tools.md) — tool index - [use-toolbox-in-hosted-agent.md § Recommendation: enable Tool Search](use-toolbox-in-hosted-agent.md#-recommendation-enable-tool-search) diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/agent-tools.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/agent-tools.md new file mode 100644 index 000000000..b201df47c --- /dev/null +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/agent-tools.md @@ -0,0 +1,51 @@ +# Agent Tools + +This file is the **index** for every tool an agent can use. For each tool, it points to a dedicated reference file, and — where the tool is also available through a [toolbox](../../use-toolbox-in-hosted-agent.md) — lists the toolbox `type` value. + +Two delivery paths exist: + +- **Prompt agent** — the agent definition declares tool classes directly (`CodeInterpreterTool`, `MCPTool`, …). Use the SDK class column and the per-tool reference. +- **Hosted agent via toolbox** — the agent connects to a single MCP endpoint that exposes all tools declared in a toolbox version. Use the `type` column and see [use-toolbox-in-hosted-agent.md](../../use-toolbox-in-hosted-agent.md). For wiring the underlying project connection (catalog tile or generic remote MCP), see [foundry-tool-catalog.md](../../foundry-tool-catalog.md). + +> 💡 **Authoritative tool shapes:** the source-of-truth for every tool's wire shape is the **Foundry Agents typespec** on the `main` branch of [`Azure/azure-rest-api-specs`](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/cognitiveservices). When in doubt about a field name, default, or new tool type that isn't yet documented here, load the typespec directly — it's updated as tools are added/changed. + +## Tool Summary + +| Tool | Prompt-agent SDK class | Connection? | Reference | +|------|------------------------|-------------|-----------| +| Code Interpreter | `CodeInterpreterTool` | No | [tool-code-interpreter.md](tool-code-interpreter.md) | +| Function calling (client-side) | `FunctionTool` | No | [tool-function-calling.md](tool-function-calling.md) | +| File Search | `FileSearchTool` | No (vector store required) | [tool-file-search.md](tool-file-search.md) | +| Web Search (preview) | `WebSearchPreviewTool` | No (basic Bing); **Yes** for Grounding with Bing Custom Search — the connection scopes grounding to specific domains | [tool-web-search.md](tool-web-search.md) | +| Bing Grounding | `BingGroundingTool` | Yes (Bing) | [tool-bing-grounding.md](tool-bing-grounding.md) | +| Azure AI Search | `AzureAISearchTool` | Yes (Search) | [tool-azure-ai-search.md](tool-azure-ai-search.md) | +| MCP server (remote) | `MCPTool` | Optional (none / static key / project MI / OAuth) | [tool-mcp.md](tool-mcp.md); toolbox attach via [foundry-tool-catalog.md](../../foundry-tool-catalog.md) | +| OpenAPI tool | (n/a as a single class) | Conditional — `connection` auth requires `project_connection_id`; **`managed_identity` auth does NOT** (the project MI is used directly with an `audience`) | [tool-openapi.md](tool-openapi.md) | +| Agent-to-Agent (A2A) | (n/a as a single class) | Optional | [tool-a2a.md](tool-a2a.md) | +| Agent Memory | `MemorySearchPreviewTool` | Yes (project MI + embedding model) | [tool-memory.md](tool-memory.md) | +| **Work IQ (preview)** | `WorkIQPreviewTool` | Yes (Work IQ BYO-Entra-app OAuth connection) | [tool-work-iq.md](tool-work-iq.md) | +| **Fabric IQ (preview)** | `FabricIQPreviewTool` | Yes (Fabric IQ Entra-app OAuth or managed-OAuth connection) | [tool-fabric-iq.md](tool-fabric-iq.md) | + +> ⚠️ **Default for web search:** Use `WebSearchPreviewTool` (`type: web_search`) unless the user explicitly requests Bing Grounding or Bing Custom Search. + +> Combine multiple tools on one agent or one toolbox version. The model decides which to invoke. For multi-tool toolbox limits (at most one unnamed tool per type, unique `server_label` per MCP tool) see [toolbox-reference.md](../../toolbox-reference.md#multi-tool-toolbox-constraint). + +## How to use this index + +When you need details for a specific tool, **load that tool's reference file directly** — each one is self-contained (shape, requirements, references). Don't try to keep all tools in context at once. + +For the toolbox runtime contract (endpoint, auth, MCP protocol, citation patterns, troubleshooting) see [toolbox-reference.md](../../toolbox-reference.md). For wiring a toolbox into a hosted agent (env vars, samples, tracing) see [use-toolbox-in-hosted-agent.md](../../use-toolbox-in-hosted-agent.md). + +## Adjacent (not a `type` in a toolbox version) + +- **Agent Memory** — use the `MemorySearchPreviewTool` SDK class on prompt agents; for hosted agents, configure the memory store via the project (separate from the toolbox). See [tool-memory.md](tool-memory.md). +- **Routines (preview)** — not a tool; an agent **trigger** (`schedule` / `timer` / `github_issue` / `custom`) that invokes an existing agent. Event-based routines are powered by the same **Connector Namespace** that backs catalog-MCP / managed-MCP connectors. See the [public Routines docs](https://learn.microsoft.com/azure/foundry/agents/how-to/use-routines). + +## References + +- **[Foundry Agents typespec (`main`)](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/cognitiveservices)** — authoritative tool shapes +- [Tool Catalog](https://learn.microsoft.com/azure/foundry/agents/concepts/tool-catalog) +- [Toolbox (preview)](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox) +- [use-toolbox-in-hosted-agent.md](../../use-toolbox-in-hosted-agent.md) — wiring a toolbox into a hosted agent +- [toolbox-reference.md](../../toolbox-reference.md) — toolbox runtime contract +- [foundry-tool-catalog.md](../../foundry-tool-catalog.md) — project connections for remote tools diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-a2a.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-a2a.md new file mode 100644 index 000000000..fc72d037e --- /dev/null +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-a2a.md @@ -0,0 +1,22 @@ +# Tool — Agent-to-Agent (A2A, preview) + +Call another Foundry agent as if it were a tool. Useful for composing specialist agents into an orchestrator. + +## Toolbox shape + +```json +{ + "type": "a2a_preview", + "name": "", + "description": "", + "base_url": "", + "project_connection_id": "" +} +``` + +Auth is either anonymous (for the same project) or via a project connection that holds credentials for the remote agent's host. + +## References + +- [A2A tool documentation](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/agent-to-agent) +- [agent-tools.md](agent-tools.md) — tool index diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-azure-ai-search.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-azure-ai-search.md similarity index 92% rename from plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-azure-ai-search.md rename to plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-azure-ai-search.md index 213ec14ed..d0b12497a 100644 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-azure-ai-search.md +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-azure-ai-search.md @@ -9,7 +9,7 @@ Ground agent responses with data from an Azure AI Search vector index. Requires - One or more `Collection(Edm.Single)` vector fields (searchable) - At least one retrievable text field with content for citations - A retrievable field with source URL for citation links -- A [project connection](../../../project/connections.md) between your Foundry project and search service +- A [project connection](../../../../../project/connections.md) between your Foundry project and search service - `azure-ai-projects` package (`pip install azure-ai-projects --pre`) ## Required RBAC Roles @@ -25,7 +25,7 @@ For **keyless authentication** (recommended), assign these roles to the **Foundr ## Connection Setup -A project connection between your Foundry project and the Azure AI Search resource is required. See [Project Connections](../../../project/connections.md) for connection management via Foundry MCP tools. +A project connection between your Foundry project and the Azure AI Search resource is required. See [Project Connections](../../../../../project/connections.md) for connection management via Foundry MCP tools. ## Query Types @@ -66,4 +66,4 @@ A project connection between your Foundry project and the Azure AI Search resour - [Azure AI Search tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/azure-ai-search?view=foundry) - [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry) -- [Project Connections](../../../project/connections.md) +- [Project Connections](../../../../../project/connections.md) diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-bing-grounding.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-bing-grounding.md similarity index 93% rename from plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-bing-grounding.md rename to plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-bing-grounding.md index 59b1fd9e3..82d9c2ad9 100644 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-bing-grounding.md +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-bing-grounding.md @@ -16,13 +16,13 @@ Access real-time web information via Bing Search. Unlike the [Web Search tool](t - A [Grounding with Bing Search resource](https://portal.azure.com/#create/Microsoft.BingGroundingSearch) in Azure portal - `Contributor` or `Owner` role at subscription/RG level to create Bing resource and get keys - `Foundry Project Manager` role on the project to create a connection -- A project connection configured with the Bing resource key — see [connections](../../../project/connections.md) +- A project connection configured with the Bing resource key — see [connections](../../../../../project/connections.md) ## Setup 1. Register the Bing provider: `az provider register --namespace 'Microsoft.Bing'` 2. Create a Grounding with Bing Search resource in the Azure portal -3. Create a project connection with the Bing resource key — see [connections](../../../project/connections.md) +3. Create a project connection with the Bing resource key — see [connections](../../../../../project/connections.md) 4. Set `BING_PROJECT_CONNECTION_NAME` environment variable ## Important Disclosures @@ -46,5 +46,5 @@ Access real-time web information via Bing Search. Unlike the [Web Search tool](t - [Bing Grounding tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/bing-grounding?view=foundry) - [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry) - [Grounding with Bing Terms](https://www.microsoft.com/bing/apis/grounding-legal-enterprise) -- [Connections Guide](../../../project/connections.md) +- [Connections Guide](../../../../../project/connections.md) - [Web Search Tool (default)](tool-web-search.md) diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-code-interpreter.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-code-interpreter.md similarity index 91% rename from plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-code-interpreter.md rename to plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-code-interpreter.md index 33cc0593d..23e1d2c97 100644 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-code-interpreter.md +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-code-interpreter.md @@ -22,4 +22,4 @@ No other fields. Only one `code_interpreter` per toolbox version (unnamed tool). - [Code Interpreter tool documentation](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/code-interpreter) - [agent-tools.md](agent-tools.md) — tool index -- [toolbox-reference.md](toolbox-reference.md) — endpoint, auth, and MCP protocol details +- [toolbox-reference.md](../../toolbox-reference.md) — endpoint, auth, and MCP protocol details diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-fabric-iq.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-fabric-iq.md similarity index 95% rename from plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-fabric-iq.md rename to plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-fabric-iq.md index 04ea56fa4..c5381c28f 100644 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-fabric-iq.md +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-fabric-iq.md @@ -34,4 +34,4 @@ Connect an agent to Microsoft Fabric data — Ontology, Fabric data agents, and For the full Entra app setup, connection-creation walkthrough, and troubleshooting, see [Fabric IQ tool documentation](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/fabric-iq). - [agent-tools.md](agent-tools.md) — tool index -- [foundry-tool-catalog.md](foundry-tool-catalog.md) — connection shape for Fabric IQ +- [foundry-tool-catalog.md](../../foundry-tool-catalog.md) — connection shape for Fabric IQ diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-file-search.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-file-search.md similarity index 100% rename from plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-file-search.md rename to plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-file-search.md diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-function-calling.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-function-calling.md similarity index 100% rename from plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-function-calling.md rename to plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-function-calling.md diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-mcp.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-mcp.md similarity index 91% rename from plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-mcp.md rename to plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-mcp.md index 0a70e5931..30b0fa3fa 100644 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-mcp.md +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-mcp.md @@ -5,14 +5,14 @@ Connect agents to remote MCP servers to extend capabilities with external tools ## Prerequisites - A remote MCP server endpoint (e.g., `https://api.githubcopilot.com/mcp`) -- For authenticated servers: a [project connection](../../../project/connections.md) storing credentials +- For authenticated servers: a [project connection](../../../../../project/connections.md) storing credentials - RBAC: **Contributor** or **Owner** role on the Foundry project ## Authenticated Server Connections For authenticated MCP servers, create an `api_key` project connection to store credentials. Unauthenticated servers (public endpoints) don't need a connection — omit `project_connection_id`. -See [Project Connections](../../../project/connections.md) for connection management via Foundry MCP tools. +See [Project Connections](../../../../../project/connections.md) for connection management via Foundry MCP tools. ## MCPTool Parameters @@ -63,4 +63,4 @@ Agent Service only accepts **remote** MCP endpoints. To use a local server, depl - [MCP tool documentation](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/mcp?view=foundry) - [Tool Catalog](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/tool-catalog?view=foundry) -- [Project Connections](../../../project/connections.md) +- [Project Connections](../../../../../project/connections.md) diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-memory.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-memory.md similarity index 99% rename from plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-memory.md rename to plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-memory.md index 32537ed06..b2f761898 100644 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-memory.md +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-memory.md @@ -98,7 +98,7 @@ The `scope` parameter partitions memory per user: | Auth/authorization error | Identity or managed identity lacks required roles | Verify roles in Authorization section; refresh access token for REST | | Memories don't appear after conversation | Updates are debounced or still processing | Increase wait time or call update API with `update_delay=0` | | Memory search returns no results | Scope mismatch between update and search | Use same scope value for storing and retrieving memories | -| Agent response ignores stored memory | Agent not configured with memory search tool | Confirm agent definition includes `MemorySearchTool` with correct store name | +| Agent response ignores stored memory | Agent not configured with memory search tool | Confirm agent definition includes `MemorySearchPreviewTool` with correct store name | | No embedding model available | Embedding deployment missing | Deploy an embedding model — see Check Embedding Model section | ## References diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-openapi.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-openapi.md similarity index 87% rename from plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-openapi.md rename to plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-openapi.md index 22926e0ce..3f5a87797 100644 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-openapi.md +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-openapi.md @@ -22,10 +22,10 @@ Expose a REST API to the agent by attaching its OpenAPI 3.x spec. The platform p ## Multi-entry rules -Multiple `openapi` entries are allowed in one toolbox **only if** each entry's spec defines a distinct `info.title` (the title is the implicit identifier). See [toolbox-reference.md § Multi-Tool Toolbox Constraint](toolbox-reference.md#multi-tool-toolbox-constraint). +Multiple `openapi` entries are allowed in one toolbox **only if** each entry's spec defines a distinct `info.title` (the title is the implicit identifier). See [toolbox-reference.md § Multi-Tool Toolbox Constraint](../../toolbox-reference.md#multi-tool-toolbox-constraint). ## References - [OpenAPI tool documentation](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/openapi) - [agent-tools.md](agent-tools.md) — tool index -- [foundry-tool-catalog.md](foundry-tool-catalog.md) — project connections for the `connection` auth path +- [foundry-tool-catalog.md](../../foundry-tool-catalog.md) — project connections for the `connection` auth path diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-web-search.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-web-search.md similarity index 100% rename from plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-web-search.md rename to plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-web-search.md diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-work-iq.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-work-iq.md similarity index 86% rename from plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-work-iq.md rename to plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-work-iq.md index d7beefd5e..44ea781c5 100644 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/references/tool-work-iq.md +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/tools/prompt-agent/tool-work-iq.md @@ -2,7 +2,7 @@ Connect an agent to the user's Microsoft 365 work context — email, meetings, files, chats — through **Work IQ**. Work IQ runs as an A2A peer; every request runs in the context of the signed-in user and honors all Microsoft 365 permissions and sensitivity labels. -> 🚦 **Toolbox creation gate:** before creating a toolbox/connection, you MUST read the boundary rules in [create-hosted.md → Toolbox creation boundary](../create-hosted.md#toolbox-creation-boundary) and follow them, then continue with the rest of this file. +> 🚦 **Toolbox creation gate:** before creating a toolbox/connection, you MUST read the boundary rules in [create-hosted.md → Toolbox creation boundary](../../../create-hosted.md#toolbox-creation-boundary) and follow them, then continue with the rest of this file. ## Toolbox shape @@ -26,4 +26,4 @@ Connect an agent to the user's Microsoft 365 work context — email, meetings, f For the full Entra app setup, ARM connection-creation payload (`category: RemoteA2A`), and troubleshooting, see [Work IQ tool documentation](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/work-iq). - [agent-tools.md](agent-tools.md) — tool index -- [foundry-tool-catalog.md](foundry-tool-catalog.md) — RemoteA2A connection shape +- [foundry-tool-catalog.md](../../foundry-tool-catalog.md) — RemoteA2A connection shape diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md index 7fefc4607..c3fc134ae 100644 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md @@ -8,7 +8,7 @@ Hosted agents access Foundry-managed tools through a **Toolbox MCP endpoint**. U > > 📘 For wiring a remote tool (catalog tile or generic MCP server) into a project connection that a toolbox can attach to, see [foundry-tool-catalog.md](foundry-tool-catalog.md). > -> 📘 For the full list of supported tool types and their per-type fields, see [agent-tools.md](agent-tools.md) and the per-tool `tool-*.md` files. +> 📘 For the supported tool types and their per-type fields, see the table below and the public [Toolbox docs (Configure tools)](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox#configure-tools). > 💡 **This skill is scoped to *consuming* an existing toolbox from agent code** — endpoint resolution, env-var contract, payload shape gathered before agent runtime, verification, and tracing. **Toolbox and connection CRUD belongs in [Foundry Toolkit (VS Code)](https://code.visualstudio.com/docs/intelligentapps/tool-catalog) or the [Foundry Portal](https://ai.azure.com/)** — those surfaces give you tool browsing, metadata, connection wizards, and validation. Use the imperative `azd ai` CLI only for *operational* tasks (retarget the default version, smoke-test an endpoint). @@ -56,24 +56,24 @@ Once the user supplies the toolbox name/endpoint — either an existing one or a ## Available tool types -The full set is documented in [agent-tools.md](agent-tools.md) and — authoritatively — in the public [Toolbox docs (Configure tools)](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox#configure-tools). At time of writing the supported `type` values are: - -| `type` | Tool | Connection required? | Detail | -|---|---|---|---| -| `mcp` | Remote MCP server (third-party via catalog, BYO OAuth, or generic) | Optional (none / static key / project MI / OAuth) | [tool-mcp.md](tool-mcp.md) | -| `web_search` | Web search (basic Bing; optional `web_search.custom_search_configuration` for Bing Custom Search to scope grounding to specific domains) | No (basic); Yes for Custom Search | [tool-web-search.md](tool-web-search.md) | -| `azure_ai_search` | Azure AI Search index | Yes (Search service connection) | [tool-azure-ai-search.md](tool-azure-ai-search.md) | -| `code_interpreter` | Sandboxed Python execution | No | [tool-code-interpreter.md](tool-code-interpreter.md) | -| `file_search` | Vector-store-backed retrieval over uploaded files | No (vector store is part of the toolbox) | [tool-file-search.md](tool-file-search.md) | -| `openapi` | REST API exposed via an OpenAPI 3.x spec | Conditional (`connection` requires `project_connection_id`; `managed_identity` does not — uses project MI + `audience`) | [tool-openapi.md](tool-openapi.md) | -| `a2a_preview` | Call another Foundry agent as a tool | Optional | [tool-a2a.md](tool-a2a.md) | -| `work_iq_preview` | Microsoft 365 work context (mail / meetings / files / chats) via Work IQ | Yes (Work IQ `RemoteA2A` OAuth connection; BYO Entra app; M365 Copilot license per user) | [tool-work-iq.md](tool-work-iq.md) | -| `fabric_iq_preview` | Microsoft Fabric data (Ontology / Fabric data agent / Power BI semantic model) | Yes (Fabric IQ OAuth connection; tenant admin consent) | [tool-fabric-iq.md](tool-fabric-iq.md) | -| `toolbox_search_preview` | **Tool Search** — a directive (not a tool) that swaps `tools/list` for `tool_search` + `call_tool` meta-tools | No | [tool-tool-search.md](tool-tool-search.md) | +The full set is documented — authoritatively — in the public [Toolbox docs (Configure tools)](https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox#configure-tools). At time of writing the supported `type` values are: + +| `type` | Tool | Connection required? | +|---|---|---| +| `mcp` | Remote MCP server (third-party via catalog, BYO OAuth, or generic) | Optional (none / static key / project MI / OAuth) | +| `web_search` | Web search (basic Bing; optional `web_search.custom_search_configuration` for Bing Custom Search to scope grounding to specific domains) | No (basic); Yes for Custom Search | +| `azure_ai_search` | Azure AI Search index | Yes (Search service connection) | +| `code_interpreter` | Sandboxed Python execution | No | +| `file_search` | Vector-store-backed retrieval over uploaded files | No (vector store is part of the toolbox) | +| `openapi` | REST API exposed via an OpenAPI 3.x spec | Conditional (`connection` requires `project_connection_id`; `managed_identity` does not — uses project MI + `audience`) | +| `a2a_preview` | Call another Foundry agent as a tool | Optional | +| `work_iq_preview` | Microsoft 365 work context (mail / meetings / files / chats) via Work IQ | Yes (Work IQ `RemoteA2A` OAuth connection; BYO Entra app; M365 Copilot license per user) | +| `fabric_iq_preview` | Microsoft Fabric data (Ontology / Fabric data agent / Power BI semantic model) | Yes (Fabric IQ OAuth connection; tenant admin consent) | +| `toolbox_search_preview` | **Tool Search** — a directive (not a tool) that swaps `tools/list` for `tool_search` + `call_tool` meta-tools | No | **Adjacent (not a `type` in a toolbox version):** -- **Agent Memory** — use the `MemorySearchTool` SDK class on prompt agents; for hosted agents, configure the memory store via the project (separate from the toolbox). See [tool-memory.md](tool-memory.md). +- **Agent Memory** — use the `MemorySearchPreviewTool` SDK class on prompt agents; for hosted agents, configure the memory store via the project (separate from the toolbox). See [tool-memory.md](tools/prompt-agent/tool-memory.md). - **Routines (preview)** — not a tool; an agent **trigger** (`schedule` / `timer` / `github_issue` / `custom`) that invokes an existing agent. See the [public Routines docs](https://learn.microsoft.com/azure/foundry/agents/how-to/use-routines). ## Information to Gather Before Building a Toolbox Payload diff --git a/plugin/skills/microsoft-foundry/references/sdk/foundry-sdk-py.md b/plugin/skills/microsoft-foundry/references/sdk/foundry-sdk-py.md index 39e086061..9e53dacc4 100644 --- a/plugin/skills/microsoft-foundry/references/sdk/foundry-sdk-py.md +++ b/plugin/skills/microsoft-foundry/references/sdk/foundry-sdk-py.md @@ -150,7 +150,7 @@ agent = project_client.agents.create_version( ) ``` -> 💡 **Tip:** `WebSearchPreviewTool` requires no external resource or connection. For Bing Grounding (which requires a dedicated Bing resource and project connection), see [Bing Grounding reference](../../foundry-agent/create/references/tool-bing-grounding.md). +> 💡 **Tip:** `WebSearchPreviewTool` requires no external resource or connection. For Bing Grounding (which requires a dedicated Bing resource and project connection), see [Bing Grounding reference](../../foundry-agent/create/references/tools/prompt-agent/tool-bing-grounding.md). ### Interacting with Agents From 6af6cac6d7b6e627c8a1645de6c9fef54c87a1cc Mon Sep 17 00:00:00 2001 From: Xiaofu Huang Date: Fri, 17 Jul 2026 14:58:55 +0800 Subject: [PATCH 2/2] fix(foundry-agent): make hosted-agent memory guidance self-contained Address PR review: the hosted-agent page linked to the prompt-agent-scoped tool-memory.md and told readers to attach MemorySearchPreviewTool, which is the wrong path for hosted agents. Hosted agents configure memory at the project level, so state that inline and link the public Memory docs instead. Co-Authored-By: Claude --- .../create/references/use-toolbox-in-hosted-agent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md index c3fc134ae..a498d1bb6 100644 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md @@ -73,7 +73,7 @@ The full set is documented — authoritatively — in the public [Toolbox docs ( **Adjacent (not a `type` in a toolbox version):** -- **Agent Memory** — use the `MemorySearchPreviewTool` SDK class on prompt agents; for hosted agents, configure the memory store via the project (separate from the toolbox). See [tool-memory.md](tools/prompt-agent/tool-memory.md). +- **Agent Memory** — for hosted agents, configure the memory store at the **project** level (separate from the toolbox); it is not a toolbox `type` and is not wired through agent code. See the public [Memory docs](https://learn.microsoft.com/azure/ai-foundry/agents/how-to/memory-usage?view=foundry). - **Routines (preview)** — not a tool; an agent **trigger** (`schedule` / `timer` / `github_issue` / `custom`) that invokes an existing agent. See the [public Routines docs](https://learn.microsoft.com/azure/foundry/agents/how-to/use-routines). ## Information to Gather Before Building a Toolbox Payload