diff --git a/plugin/skills/microsoft-foundry/foundry-agent/create/references/toolbox.md b/plugin/skills/microsoft-foundry/foundry-agent/create/references/toolbox.md index 4b739ef55..a68db17ce 100644 --- a/plugin/skills/microsoft-foundry/foundry-agent/create/references/toolbox.md +++ b/plugin/skills/microsoft-foundry/foundry-agent/create/references/toolbox.md @@ -7,9 +7,10 @@ Hosted agents access Foundry-managed tools through a **Toolbox MCP endpoint**. U | Property | Value | |----------|-------| | **Toolbox Docs** | https://learn.microsoft.com/azure/foundry/agents/how-to/tools/toolbox | -| **Hosted Agent + Toolbox + Agent Framework SDK** — default | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox | -| **Toolbox Samples — Python** | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox, https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/bring-your-own/responses | -| **Toolbox Samples — C# (.NET)** | https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/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 @@ -40,10 +41,10 @@ Otherwise, ask: _"Do you have an existing Foundry Toolbox, or should I help crea | 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), sample [`agent.manifest.yaml`](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/agent.manifest.yaml) | +| **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), [Toolbox docs — VS Code 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 @@ -52,18 +53,19 @@ The sample repo provides integration patterns for both Python and C#. Read the s **Python samples:** -| Pattern | When to use | Hosted Agent Sample | Standalone Sample | -|---------|-------------|--------------------|---------| -| **Agent Framework (MAF)** — recommended | Default choice for hosted agents | [`04-foundry-toolbox/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox) | [`toolbox/maf/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox/maf) | -| **LangGraph** | User already uses LangGraph | — | [`toolbox/langgraph/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox/langgraph) | -| **Copilot SDK** | GitHub Copilot SDK with toolbox tools | — | [`toolbox/copilot-sdk/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/toolbox/copilot-sdk) | -| **Bring Your Own (generic MCP)** | Any framework or custom code | [`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) | — | +| 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:** -| Pattern | When to use | Sample | -|---------|-------------|--------| -| **Agent Framework (MAF)** — recommended | Default choice for .NET hosted agents | [`csharp/toolbox/maf/`](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/toolbox/maf) | +| 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`). @@ -163,7 +165,7 @@ curl -sS -X POST "$TOOLBOX_URL" \ -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/toolbox/main.py) — it implements `initialize`, `list_tools`, and `call_tool` using raw `httpx` calls. +> 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