## About tool use & agents

Tool use enables developers to build agentic applications that connect to external tools, do reasoning, and perform actions.

The Chat endpoint comes with built-in tool use capabilities such as function calling, multi-step reasoning, and citation generation.

This quickstart guide shows you how to utilize tool use with the Chat endpoint.

::::::steps{titleSize="h2"}
:::::step{title="Setup"}
First, install the Cohere Python SDK with the following command.

```bash
pip install -U cohere
```

Next, import the library and create a client.

::::tabs
:::tab{title="Cohere Platform"}
```python PYTHON
import cohere

co = cohere.ClientV2(
    "COHERE_API_KEY"
)  # Get your free API key here: https://dashboard.cohere.com/api-keys
```
:::

:::tab{title="Private Deployment"}
```python PYTHON
import cohere

co = cohere.ClientV2(
    api_key="",  # Leave this blank
    base_url="<YOUR_DEPLOYMENT_URL>",
)
```
:::

:::tab{title="Bedrock"}
```python PYTHON
import cohere

co = cohere.BedrockClientV2(
    aws_region="AWS_REGION",
    aws_access_key="AWS_ACCESS_KEY_ID",
    aws_secret_key="AWS_SECRET_ACCESS_KEY",
    aws_session_token="AWS_SESSION_TOKEN",
)

# Get the model name: https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html
```
:::

:::tab{title="SageMaker"}
```python PYTHON
import cohere

co = cohere.SagemakerClientV2(
    aws_region="AWS_REGION",
    aws_access_key="AWS_ACCESS_KEY_ID",
    aws_secret_key="AWS_SECRET_ACCESS_KEY",
    aws_session_token="AWS_SESSION_TOKEN",
)
```
:::

:::tab{title="Azure AI"}
```python PYTHON
import cohere

co = cohere.ClientV2(
    api_key="AZURE_API_KEY",
    base_url="AZURE_ENDPOINT",  # example: "https://cohere-command-r-plus-08-2024-xyz.eastus.models.ai.azure.com/"
)
```
:::
::::
:::::

:::step{title="Tool Definition"}
First, we need to set up the tools. A tool can be any function or service that can receive and send objects.

We also need to define the tool schemas in a format that can be passed to the Chat endpoint. The schema must contain the following fields: `name`, `description`, and `parameters`.

```python PYTHON
def get_weather(location):
    # Implement your tool calling logic here
    return [{"temperature": "20C"}]
    # Return a list of objects e.g. [{"url": "abc.com", "text": "..."}, {"url": "xyz.com", "text": "..."}]


functions_map = {"get_weather": get_weather}

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "gets the weather of a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "the location to get weather, example: San Fransisco, CA",
                    }
                },
                "required": ["location"],
            },
        },
    },
]
```
:::

:::::step{title="Tool Calling"}
Next, pass the tool schema to the Chat endpoint together with the user message.

The LLM will then generate the tool calls (if any) and return the `tool_plan` and `tool_calls` objects.

::::tabs
:::tab{title="Cohere Platform"}
```python PYTHON
messages = [
    {"role": "user", "content": "What's the weather in Toronto?"}
]

response = co.chat(
    model="command-a-plus-05-2026", messages=messages, tools=tools
)

if response.message.tool_calls:
    messages.append(response.message)
    print(response.message.tool_calls)

```
:::

:::tab{title="Private Deployment"}
```python PYTHON
messages = [
    {"role": "user", "content": "What's the weather in Toronto?"}
]

response = co.chat(
    model="command-a-plus-05-2026", messages=messages, tools=tools
)

if response.message.tool_calls:
    messages.append(response.message)
    print(response.message.tool_calls)
```
:::

:::tab{title="Bedrock"}
```python PYTHON
messages = [
    {"role": "user", "content": "What's the weather in Toronto?"}
]

response = co.chat(
    model="YOUR_MODEL_NAME", messages=messages, tools=tools
)

if response.message.tool_calls:
    messages.append(response.message)
    print(response.message.tool_calls)
```
:::

:::tab{title="SageMaker"}
```python PYTHON
messages = [
    {"role": "user", "content": "What's the weather in Toronto?"}
]

response = co.chat(
    model="YOUR_ENDPOINT_NAME", messages=messages, tools=tools
)

if response.message.tool_calls:
    messages.append(response.message)
    print(response.message.tool_calls)
```
:::

:::tab{title="Azure AI"}
```python PYTHON
messages = [
    {"role": "user", "content": "What's the weather in Toronto?"}
]

response = co.chat(
    model="model",  # Pass a dummy string
    messages=messages,
    tools=tools,
)

if response.message.tool_calls:
    messages.append(response.message)
    print(response.message.tool_calls)
```
:::
::::

```mdx wordWrap
[ToolCallV2(id='get_weather_776n8ctsgycn', type='function', function=ToolCallV2Function(name='get_weather', arguments='{"location":"Toronto"}'))]
```
:::::

:::step{title="Tool Execution"}
Next, the tools called will be executed based on the arguments generated in the tool calling step earlier.

```python PYTHON
import json

if response.message.tool_calls:
    for tc in response.message.tool_calls:
        tool_result = functions_map[tc.function.name](
            **json.loads(tc.function.arguments)
        )
        tool_content = []
        for data in tool_result:
            tool_content.append(
                {
                    "type": "document",
                    "document": {"data": json.dumps(data)},
                }
            )
            # Optional: add an "id" field in the "document" object, otherwise IDs are auto-generated
        messages.append(
            {
                "role": "tool",
                "tool_call_id": tc.id,
                "content": tool_content,
            }
        )
```
:::

:::::step{title="Response Generation"}
The results are passed back to the LLM, which generates the final response.

::::tabs
:::tab{title="Cohere Platform"}
```python PYTHON
response = co.chat(
    model="command-a-plus-05-2026", messages=messages, tools=tools
)
print(response.message.content[0].text)
```
:::

:::tab{title="Private Deployment"}
```python PYTHON
response = co.chat(
    model="command-a-plus-05-2026", messages=messages, tools=tools
)
print(response.message.content[0].text)
```
:::

:::tab{title="Bedrock"}
```python PYTHON
response = co.chat(
    model="YOUR_MODEL_NAME", messages=messages, tools=tools
)
print(response.message.content[0].text)
```
:::

:::tab{title="SageMaker"}
```python PYTHON
response = co.chat(
    model="YOUR_ENDPOINT_NAME", messages=messages, tools=tools
)
print(response.message.content[0].text)
```
:::

:::tab{title="Azure AI"}
```python PYTHON
response = co.chat(
    model="model",  # Pass a dummy string
    messages=messages,
    tools=tools,
)
print(response.message.content[0].text)
```
:::
::::

```mdx wordWrap
It is 20C in Toronto.
```
:::::

:::step{title="Citation Generation"}
The response object contains a `citations` field, which contains specific text spans from the documents on which the response is grounded.

```python PYTHON
if response.message.citations:
    for citation in response.message.citations:
        print(citation, "\n")
```

```mdx wordWrap
start=6 end=9 text='20C' sources=[ToolSource(type='tool', id='get_weather_776n8ctsgycn:0', tool_output={'temperature': '20C'})] 
```
:::
::::::

## Further Resources

- [Chat endpoint API reference](/api)
- [Documentation on tool use](/guides/text-generation-tools)
- [LLM University module on tool use](https://cohere.com/llmu#tool-use)

## Related pages

- [Retrieval augmented generation (RAG) - quickstart](./cohere-platform-v2-get-started-quickstart-rag-quickstart.md)
- [Reranking - quickstart](./cohere-platform-v2-get-started-quickstart-reranking-quickstart.md)
- [Semantic search - quickstart](./cohere-platform-v2-get-started-quickstart-sem-search-quickstart.md)
- [Text generation - quickstart](./cohere-platform-v2-get-started-quickstart-text-gen-quickstart.md)
- [Audio Transcription - quickstart](./cohere-platform-v2-get-started-quickstart-audio-transcription-quickstart.md)
- [Document Parsing - quickstart](./cohere-platform-v2-get-started-quickstart-parse-quickstart.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.