How to call ai search tool in agent playground?

Question

I am trying to include the ai search tool in my agent project. The resource has been added to the agent, but when the agent tries to call the ai search tool, the following error is returned:

tool_user_error: Error: search_service_request_error; Unable to connect to Azure AI Search Resource. Please ensure the Azure AI Search Connection has the correct endpoint and the search resouce has appropriate network settings for the agents setup. Cannot connect to host. ssl:default [DNS server returned answer with no data]

I am using api key authentication and checked the endpoint and key is correct. All the resource are in a virtual network, and I have added private endpoints for all of them. I also tried to make them public to network, but the above error still exists. Is there other way to check what is the issue, or how to solve the above error? Thanks!

Answer 1

Hello Elvis,

Below is the end-to-end checklist for getting the Azure AI Search tool to fire inside the Agent Playground. Work through the steps in order—nine times out of ten the tool won’t appear in the run trace because one of these prerequisites is missing.

✅ Step	What to do	Why it matters
1. Build or pick a ready-made Search index	In the Azure Portal, create an Azure AI Search service and an index that contains at minimum a content (string) field and, if you want vector search, a contentVector field with an attached vector profile.	The agent can only query fields that meet the Search tool’s schema requirements.
1. Build or pick a ready-made Search index	In the Azure Portal, create an Azure AI Search service and an index that contains at minimum a content (string) field and, if you want vector search, a contentVector field with an attached vector profile.	The agent can only query fields that meet the Search tool’s schema requirements.
2. Create the connection in Foundry	Project → Connections → Add connection → Azure AI Search. Provide the service URL, admin key, index name, and (optionally) the vector profile name. Save once you see the green “Connected” tick.	The tool itself is just a wrapper around this connection—no connection, no tool call.
3. Attach the tool to your agent	Agents → select your agent → Setup pane → Knowledge → Add → choose Azure AI Search → pick the connection you created → Save.	The agent’s runtime only considers tools that are explicitly listed here.
4. Add a short “use the Search tool” hint to System instructions	Example: “When the user asks for facts that may be in our product docs, call the Azure AI Search tool.”	Large-language models decide on their own which tool to invoke. A one-line nudge raises the likelihood they’ll pick Search when appropriate.
5. Open the Agent Playground and ask a question that needs the index	Click Open in playground, then ask something only your index can answer—for example, “What is the warranty period for model X in the latest manual?”	The Run Trace (left rail) should now show a tool call → azure_ai_search.query() step followed by the model’s answer citing your documents.
6. Can’t see a tool call? Check the run trace	If the trace shows only CHAT_COMPLETION steps, the model never picked the tool. Either: • The question can be answered from the model’s own knowledge, or • The system prompt isn’t explicit enough, or • The index connection is invalid (look for a red ⚠️ icon).
7. Make sure service & tool are reachable	• Search service and Foundry project must be in the same region. • If the Search service has a private endpoint or IP firewall, add the Agent Service outbound IPs to its allow-list.	Network blocks silently prevent tool execution.
8. Confirm you’re under quota limits	The Free (F0) Search tier and the Agent Service free SKU cap concurrent queries. A saturated quota can make a tool call time-out and vanish from the trace.
9. (Optional) Test via SDK	python<br>from azure.ai.agent import AgentClient<br>client = AgentClient("<endpoint>", credential="<key>")<br>run = client.run(messages=[{"role":"user","content":"Ask …"}])<br>print(run.steps)<br>	Verifies outside the UI that the agent calls azure_ai_search_query with the right payload.

---

Quick sanity check

Ask: “List the chapter titles in Doc ABC.”

In the left-hand Run steps pane you should see:

tool.call: azure_ai_search_query
tool.output: {...}
chat_completion

If you don’t see the first line, revisit steps 2-4—99 % of issues trace back to a missing connection or the agent not being told when to use Search.

---

Once all green ticks are in place, the Search tool will be invoked automatically whenever the model decides extra grounding is needed—and you’ll see the citations come from your Azure AI Search index in the final answer.

Best Regards,

Jerald Felix