## Overview

This guide shows how to expose Perplexity's [Search API](/guides/agent-api-search-quickstart) to Claude as a tool. The Anthropic Messages API uses a manual tool-use loop: the model emits a `tool_use` block, you execute the tool (in this case, call `client.search.create`), and you send the result back as a `tool_result`. The loop continues until the model returns a final answer.

## Prerequisites

:::code-group
```bash Python theme={null}
pip install anthropic perplexityai
export ANTHROPIC_API_KEY="your_anthropic_key"
export PERPLEXITY_API_KEY="your_perplexity_key"
```

```bash Typescript theme={null}
npm install @anthropic-ai/sdk @perplexity-ai/perplexity_ai
export ANTHROPIC_API_KEY="your_anthropic_key"
export PERPLEXITY_API_KEY="your_perplexity_key"
```
:::

## Tool definition

Claude needs a tool description that tells it when and how to call `web_search`. The description below was tuned for Perplexity's Search API; keep it verbatim — the wording of the description and the parameter guidance is what produces good, short, keyword-style queries.

:::code-group
```python Python theme={null}
WEB_SEARCH_TOOL_DESCRIPTION = """\
Searches the web for current and factual information to answer user queries, returning relevant results with titles, URLs, and content snippets, similar to Google or Bing. Intended for questions about up-to-date or externally verified information beyond your knowledge cutoff. The tool works best with an array of short, keyword-focused queries. Complex queries that require multi-step reasoning are not supported. Time-sensitive queries are supported if the date is included in the query.

Best practices for using this tool:
- Limit the number of queries in each request to a maximum of three to maintain efficiency.
- For multi-entity questions, break them into separate, single-entity queries:
  - Preferred:
    [
      "Brand A protein powder review",
      "Brand B protein powder review"
    ]
  - Not recommended:
    [
      "Brand A vs Brand B protein powder review"
    ]

- For simple queries, keep each query straightforward and focused:
  - Preferred: ["inflation rate Canada"]
  - Not recommended: ["What is the inflation rate in Canada?"]

Each query should be short to ensure optimal tool performance. Make sure all provided examples and generated queries follow this guideline."""

QUERIES_PARAM_DESCRIPTION = (
    "An array of keyword-based search queries. Each query should be short, "
    "as longer queries may reduce performance. Do not provide more than three "
    "queries to maintain efficiency."
)

WEB_SEARCH_TOOL = {
    "name": "web_search",
    "description": WEB_SEARCH_TOOL_DESCRIPTION,
    "input_schema": {
        "type": "object",
        "properties": {
            "queries": {
                "type": "array",
                "description": QUERIES_PARAM_DESCRIPTION,
                "items": {"type": "string"},
                "minItems": 1,
                "maxItems": 3,
            },
        },
        "required": ["queries"],
    },
}
```

```typescript Typescript theme={null}
const WEB_SEARCH_TOOL_DESCRIPTION = `Searches the web for current and factual information to answer user queries, returning relevant results with titles, URLs, and content snippets, similar to Google or Bing. Intended for questions about up-to-date or externally verified information beyond your knowledge cutoff. The tool works best with an array of short, keyword-focused queries. Complex queries that require multi-step reasoning are not supported. Time-sensitive queries are supported if the date is included in the query.

Best practices for using this tool:
- Limit the number of queries in each request to a maximum of three to maintain efficiency.
- For multi-entity questions, break them into separate, single-entity queries:
  - Preferred:
    [
      "Brand A protein powder review",
      "Brand B protein powder review"
    ]
  - Not recommended:
    [
      "Brand A vs Brand B protein powder review"
    ]

- For simple queries, keep each query straightforward and focused:
  - Preferred: ["inflation rate Canada"]
  - Not recommended: ["What is the inflation rate in Canada?"]

Each query should be short to ensure optimal tool performance. Make sure all provided examples and generated queries follow this guideline.`;

const QUERIES_PARAM_DESCRIPTION =
  "An array of keyword-based search queries. Each query should be short, " +
  "as longer queries may reduce performance. Do not provide more than three " +
  "queries to maintain efficiency.";

const WEB_SEARCH_TOOL = {
  name: "web_search",
  description: WEB_SEARCH_TOOL_DESCRIPTION,
  input_schema: {
    type: "object" as const,
    properties: {
      queries: {
        type: "array" as const,
        description: QUERIES_PARAM_DESCRIPTION,
        items: { type: "string" as const },
        minItems: 1,
        maxItems: 3,
      },
    },
    required: ["queries"],
  },
};
```
:::

## Tool handler

The handler is a thin wrapper around `client.search.create`. The Search API natively accepts an array of queries (up to five), so the array Claude emits can be passed straight through.

:::code-group
```python Python theme={null}
from perplexity import Perplexity

perplexity = Perplexity()

def run_web_search(queries: list[str]) -> str:
    """Call Perplexity Search and format the results for the model."""
    response = perplexity.search.create(query=queries, max_results=5)

    lines = []
    for result in response.results:
        snippet = (result.snippet or "").strip().replace("\n", " ")
        if len(snippet) > 400:
            snippet = snippet[:400] + "…"
        lines.append(f"- {result.title}\n  {result.url}\n  {snippet}")
    return "\n\n".join(lines) if lines else "No results."
```

```typescript Typescript theme={null}
import Perplexity from "@perplexity-ai/perplexity_ai";

const perplexity = new Perplexity();

async function runWebSearch(queries: string[]): Promise<string> {
  const response = await perplexity.search.create({
    query: queries,
    max_results: 5,
  });

  const lines = response.results.map((r) => {
    const snippet = (r.snippet ?? "").trim().replace(/\n/g, " ");
    const trimmed = snippet.length > 400 ? `${snippet.slice(0, 400)}…` : snippet;
    return `- ${r.title}\n  ${r.url}\n  ${trimmed}`;
  });
  return lines.length ? lines.join("\n\n") : "No results.";
}
```
:::

## Tool-use loop

Anthropic's Messages API hands you a `stop_reason` of `"tool_use"` and one or more `ToolUseBlock` items inside `response.content`. Run each tool call, build a `tool_result` block per call (paired by `tool_use_id`), and send all results back in a single user message. Loop until `stop_reason` is no longer `"tool_use"`.

:::code-group
```python Python theme={null}
import json
from anthropic import Anthropic

claude = Anthropic()

def chat_with_search(user_prompt: str, model: str = "claude-sonnet-4-6") -> str:
    messages = [{"role": "user", "content": user_prompt}]

    while True:
        response = claude.messages.create(
            model=model,
            max_tokens=1024,
            tools=[WEB_SEARCH_TOOL],
            messages=messages,
        )

        if response.stop_reason != "tool_use":
            # Final answer — pull text blocks out of the assistant message.
            return "".join(
                block.text for block in response.content if block.type == "text"
            )

        # Append the assistant's tool-call turn to history.
        messages.append({"role": "assistant", "content": response.content})

        # Run every tool call in this turn and pair results by tool_use_id.
        tool_results = []
        for block in response.content:
            if block.type != "tool_use":
                continue
            if block.name == "web_search":
                output = run_web_search(block.input["queries"])
            else:
                output = json.dumps({"error": f"unknown tool: {block.name}"})
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": output,
            })

        messages.append({"role": "user", "content": tool_results})


if __name__ == "__main__":
    answer = chat_with_search(
        "What were the major AI infrastructure announcements this week?"
    )
    print(answer)
```

```typescript Typescript theme={null}
import Anthropic from "@anthropic-ai/sdk";

const claude = new Anthropic();

async function chatWithSearch(
  userPrompt: string,
  model = "claude-sonnet-4-6",
): Promise<string> {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: userPrompt },
  ];

  while (true) {
    const response = await claude.messages.create({
      model,
      max_tokens: 1024,
      tools: [WEB_SEARCH_TOOL],
      messages,
    });

    if (response.stop_reason !== "tool_use") {
      return response.content
        .filter((b): b is Anthropic.TextBlock => b.type === "text")
        .map((b) => b.text)
        .join("");
    }

    messages.push({ role: "assistant", content: response.content });

    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    for (const block of response.content) {
      if (block.type !== "tool_use") continue;
      let output: string;
      if (block.name === "web_search") {
        const input = block.input as { queries: string[] };
        output = await runWebSearch(input.queries);
      } else {
        output = JSON.stringify({ error: `unknown tool: ${block.name}` });
      }
      toolResults.push({
        type: "tool_result",
        tool_use_id: block.id,
        content: output,
      });
    }

    messages.push({ role: "user", content: toolResults });
  }
}

(async () => {
  const answer = await chatWithSearch(
    "What were the major AI infrastructure announcements this week?",
  );
  console.log(answer);
})();
```
:::

## Streaming

For streaming responses, use `client.messages.stream(...)` and accumulate `tool_use` blocks from the events. The model emits `input_json_delta` events with partial JSON arguments; the SDK helper accumulates them and exposes the completed `tool_use` block via `stream.get_final_message()` (Python) or `stream.finalMessage()` (TypeScript). The loop structure is otherwise identical to the non-streaming version.

:::code-group
```python Python theme={null}
with claude.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=[WEB_SEARCH_TOOL],
    messages=messages,
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()

# Inspect final.stop_reason and final.content for tool_use blocks, then
# resume the loop the same way as in the non-streaming version.
```

```typescript Typescript theme={null}
const stream = claude.messages.stream({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  tools: [WEB_SEARCH_TOOL],
  messages,
});

for await (const chunk of stream) {
  if (chunk.type === "content_block_delta" && chunk.delta.type === "text_delta") {
    process.stdout.write(chunk.delta.text);
  }
}
const final = await stream.finalMessage();
// Inspect final.stop_reason and final.content as in the non-streaming version.
```
:::

## Notes

- **Parallel tool calls.** Claude can emit multiple `tool_use` blocks in a single assistant turn. Every block must have a matching `tool_result` in the _same_ subsequent user message, paired by `tool_use_id`. To disable, set `tool_choice={"type": "auto", "disable_parallel_tool_use": True}`.
- **Result formatting.** The string returned to `tool_result.content` is what the model reads next. Including the URL alongside the snippet helps the model cite sources when it produces its final answer.
- **Errors.** To signal that a tool call failed, set `"is_error": True` on the `tool_result` block and put a short error message in `content`. The model will see the error and can recover (for example, by reformulating queries).
- **Domains and dates.** Pass `search_domain_filter`, `country`, and other Search API parameters inside `run_web_search` if you want fixed retrieval constraints. See the [Search API quickstart](/guides/agent-api-search-quickstart) for the full parameter list.

## Next Steps

::::card-grid
:::card{title="Use with OpenAI SDK" href="/guides/agent-api-search-agent-sdks-openai" icon="code"}
Wire Search API into the OpenAI Responses API.
:::

:::card{title="Use with Gemini SDK" href="/guides/agent-api-search-agent-sdks-gemini" icon="code"}
Wire Search API into Google's `google-genai` SDK.
:::

:::card{title="Search API Quickstart" href="/guides/agent-api-search-quickstart" icon="rocket"}
Full Search API parameter reference.
:::

:::card{title="Search Best Practices" href="/guides/agent-api-search-best-practices" icon="lightbulb"}
Patterns for production search workloads.
:::
::::

## Related pages

- [Use Search API with the OpenAI SDK](./agent-api-search-agent-sdks-openai.md)
- [Use Search API with the Google Gemini SDK](./agent-api-search-agent-sdks-gemini.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.