Manage Tools & Toolboxes with `azd ai`

The full azd ai toolbox CLI surface — creating, editing, versioning, and teardown. For the create→consume walkthrough and per-tool flows, see toolbox.md § Create & use a toolbox (happy path) and the Supported tool types table.

CLI surface

Command	What it does
`azd extension install azure.ai.toolboxes`	Install the toolbox CLI extension (once).
`azd ai toolbox create <name> --from-file <path>`	Create toolbox + its first version. File must list at least one connection, skill, or tool.
`azd ai toolbox connection add <toolbox> <connection> [--index ...] [--instance-name ...]`	Attach one; creates a new version (default unchanged).
`azd ai toolbox connection add <toolbox> --from-file <path>`	Attach many connections in one call; ONE new version (default unchanged). Connectionless built-ins aren't supported here — see the note under `--from-file` schema.
`azd ai toolbox connection remove <toolbox> <connection>`	Detach; creates a new version (default unchanged). Refuses to leave zero tools.
`azd ai toolbox show <name> [--version <ver>]`	Show toolbox + MCP endpoint URL.
`azd ai toolbox list`	List toolboxes.
`azd ai toolbox versions list <toolbox>`	List versions.
`azd ai toolbox publish <name> <version>`	Promote a version to default (also used to roll back).
`azd ai toolbox delete <name> [--version <ver>] [--force]`	Delete toolbox or one version.

Every mutation publishes a new immutable version but does not change the default; run azd ai toolbox publish <name> <version> to promote one.

`--from-file` schema

The YAML/JSON passed to azd ai toolbox create --from-file lists the connections to bundle, plus an optional tools: block for connectionless built-ins.

Note: azd ai toolbox connection add --from-file attaches connections only. Connectionless built-ins (the tools: block — web_search, code_interpreter, file_search, toolbox_search_preview) can't be added to an existing toolbox; recreate it with azd ai toolbox create --from-file and the full desired tool set.

description: research toolbox    # only on `create`
connections:
  - name: my-mcp                 # RemoteTool
  - name: my-search              # CognitiveSearch -- needs index
    index: products
  - name: my-a2a                 # RemoteA2A
tools:                           # connectionless built-ins (optional)
  - type: web_search
    name: web
  - type: code_interpreter
    container: { type: auto }
  - type: file_search
    vector_store_ids: ["<vector-store-id>"]   # flat: sibling of type, NOT nested under file_search
  - type: toolbox_search_preview

description is honored only on create (it names the first version).
At least one of connections, skills, or tools must be non-empty.
The connections: block is a CLI convenience alias — the CLI expands each entry into the corresponding nested tool (e.g. CognitiveSearch → an azure_ai_search tool). The raw toolbox API accepts only the tools: array, so a hand-rolled API payload must use the tool shape directly.
Attaching many entries in one --from-file call produces one new version. create publishes it as the first (default) version; connection add leaves the default unchanged until you publish.

Per-connection-kind fields

Connection kind	Extra field(s)	Notes
`RemoteTool` (MCP)	—	Just `name`.
`CognitiveSearch` (Azure AI Search)	`index`	One entry per index; repeat with different `index` values for multiple indexes.
`RemoteA2A` (A2A peer)	—	Just `name`.

Connectionless built-in tools (`tools:` block)

Built-ins with no connection are declared directly under tools: (not connections:):

`type`	Extra field(s)	Notes
`web_search`	—	Basic Bing. For Bing Custom Search, use a `GroundingWithCustomSearch` connection instead.
`code_interpreter`	`container: { type: auto }`	Sandboxed Python.
`file_search`	`vector_store_ids`	Flat: `vector_store_ids: ["vs_..."]` as a sibling of `type` (NOT nested under `file_search:`). Requires an existing vector store ID.
`toolbox_search_preview`	—	Tool Search directive; counts as the toolbox's one allowed unnamed tool.

Client-side function calling (FunctionTool) is not a toolbox tool type — it's declared on the prompt agent directly.

Multi-tool rule

Across the whole toolbox, at most ONE tool may be unnamed. Every other tool needs a unique identifier — name for built-ins, server_label for mcp (and, for openapi, a distinct info.title in each spec — see below). toolbox_search_preview counts as a tool here. Violating this returns 400 invalid_payload: Multiple tools without identifiers found. All tools except a single tool must have unique identifiers ('name' or 'server_label').

Valid combinations include:

file_search (unnamed) + one or more mcp (each with unique server_label)
web_search (unnamed) + one or more mcp
azure_ai_search (unnamed) + one or more mcp
web_search named (name: web) + toolbox_search_preview (the one unnamed tool)

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).

Connection-backed tools and connectionless built-ins can be bundled in one --from-file (built-ins go under a tools: block, not azd ai toolbox connection add) — one new version regardless of count.

References

toolbox.md — concept, create flow, supported tool types, troubleshooting
Toolbox (Configure tools)
Tool Catalog
Foundry Toolkit (VS Code) — set up tools/toolboxes
Foundry Portal

6.1 KiB Raw Permalink Blame History

Manage Tools & Toolboxes with azd ai