## Web Search Tool Overview

The web search tool for chat completions allows you to search the web for current information during a conversation. This guide explains how to use the web search tool in a chat completion and provides an example of how to use it.

You need an API key to access the Writer API. Get an API key by following the steps in the [API quickstart](https://dev.writer.com/home/quickstart). We recommend setting the API key as an environment variable in a `.env` file with the name `WRITER_API_KEY`.

### Usage Example
This example uses the web search tool to find current information about AI developments during a chat completion. To use the web search tool:

1. Create a `tools` array that specifies the web search tool.
   - The tool array should include the `type` and `function` parameters. The `function` parameter should include the `include_domains` and `exclude_domains` parameters.
2. Create a `messages` array that contains the user message that prompts the model to use the web search tool.
3. Call the `chat.chat` method with the `tools` parameter set to the `tools` array and `tool_choice` set to `auto`.

### Example Code

**cURL**

```bash
curl --location 'https://api.writer.com/v1/chat' \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $WRITER_API_KEY" \
    --data '{\n        "model": "palmyra-x5",\n        "messages": [\
            {\n                "role": "user",\n                "content": "What are the latest developments in AI technology?"\n            }\n        ],\n        "tool_choice": "auto",\n        "tools": [\
            {\n                "type": "web_search",\n                "function": {\n                    "include_domains": ["wikipedia.org", "github.com", "techcrunch.com"],\n                    "exclude_domains": ["quora.com"]\n                }\n            }\n        ]\n    }'
```

**Python**

```python
from writerai import Writer

client = Writer()  # Initialize the Writer client. If you don't pass the `api_key` parameter,
# the client looks for the `WRITER_API_KEY` environment variable.

messages = [{"role": "user", "content": "What are the latest developments in AI technology?"}]

response = client.chat.chat(
    model="palmyra-x5",
    messages=messages,
    tools=tools,  # The tools array defined earlier.
    tool_choice="auto"
)

print(response.choices[0].message.content)
```

**JavaScript**

```javascript
import { Writer } from "writer-sdk";

const client = new Writer();  // Initialize the Writer client. If you don't pass the `apiKey` parameter,
// the client looks for the `WRITER_API_KEY` environment variable.

const messages = [{role: "user", content: "What are the latest developments in AI technology?"}];

const response = await client.chat.chat({
    model: "palmyra-x5",
    messages: messages,
    tools: tools, // The tools array defined earlier.
    tool_choice: "auto"
});

console.log(response.choices[0].message.content);
```

### Understanding Tool Structure

The web search tool object has the following structure:

| Parameter | Type | Description |
| --- | --- | --- |
| `type` | `string` | The type of tool, which is `web_search` for the web search tool |
| `function` | `object` | An object containing the tool’s configuration |
| `function.include_domains` | `array` | An array of domains to include in the search results |
| `function.exclude_domains` | `array` | An array of domains to exclude from the search results |

You can pass multiple custom tools in the same request. Prebuilt tools include the web search tool, knowledge graph tool, LLM tool, and translation tool.

### Response Format

For non-streaming responses, the search results and answer are in the `choices[0].message.content` field. For streaming responses, the search results and answer are in the `choices[0].delta.content` field. The response contains a `web_search_data` field that provides:
- `query`: The search query that was submitted.
- `answer`: The generated answer based on the search results.
- `sources`: The search results found, including URLs and raw content if requested.