1
# ! pip install -U cohere
2
3
import cohere
4
5
# instantiating the old client
6
co_v1 = cohere.Client(api_key="<YOUR API KEY>")
7
8
# instantiating the new client
9
co_v2 = cohere.ClientV2(api_key="<YOUR API KEY>")

1
res = co_v1.chat(
2
    model="command-a-03-2025",
3
    preamble="You respond in concise sentences.",
4
    chat_history=[
5
        {"role": "user", "message": "Hello"},
6
        {
7
            "role": "chatbot",
8
            "message": "Hi, how can I help you today?",
9
        },
10
    ],
11
    message="I'm joining a new startup called Co1t today. Could you help me write a one-sentence introduction message to my teammates?",
12
)
13
14
print(res.text)

1
res = co_v2.chat(
2
    model="command-a-03-2025",
3
    messages=[
4
        {
5
            "role": "system",
6
            "content": "You respond in concise sentences.",
7
        },
8
        {"role": "user", "content": "Hello"},
9
        {
10
            "role": "assistant",
11
            "content": "Hi, how can I help you today?",
12
        },
13
        {
14
            "role": "user",
15
            "content": "I'm joining a new startup called Co1t today. Could you help me write a one-sentence introduction message to my teammates.",
16
        },
17
    ],
18
)
19
20
print(res.message.content[0].text)

1
res = co_v1.chat(model="command-a-03-2025", message="What is 2 + 2")
2
3
print(res.text)

1
res = co_v2.chat(
2
    model="command-a-03-2025",
3
    messages=[{"role": "user", "content": "What is 2 + 2"}],
4
)
5
6
print(res.message.content[0].text)

1
message = "I'm joining a new startup called Co1t today. Could you help me write a one-sentence introduction message to my teammates."
2
3
res = co_v1.chat_stream(model="command-a-03-2025", message=message)
4
5
for chunk in res:
6
    if chunk.event_type == "text-generation":
7
        print(chunk.text, end="")

1
message = "I'm joining a new startup called Co1t today. Could you help me write a one-sentence introduction message to my teammates."
2
3
res = co_v2.chat_stream(
4
    model="command-a-03-2025",
5
    messages=[{"role": "user", "content": message}],
6
)
7
8
for chunk in res:
9
    if chunk:
10
        if chunk.type == "content-delta":
11
            print(chunk.delta.message.content.text, end="")

1
# Define the documents
2
documents_v1 = [
3
    {
4
        "text": "Reimbursing Travel Expenses: Easily manage your travel expenses by submitting them through our finance tool. Approvals are prompt and straightforward."
5
    },
6
    {
7
        "text": "Health and Wellness Benefits: We care about your well-being and offer gym memberships, on-site yoga classes, and comprehensive health insurance."
8
    },
9
]
10
11
# The user query
12
message = "Are there fitness-related benefits?"
13
14
# Generate the response
15
res_v1 = co_v1.chat(
16
    model="command-a-03-2025",
17
    message=message,
18
    documents=documents_v1,
19
)
20
21
print(res_v1.text)

1
# Define the documents
2
documents_v2 = [
3
    {
4
        "data": {
5
            "text": "Reimbursing Travel Expenses: Easily manage your travel expenses by submitting them through our finance tool. Approvals are prompt and straightforward."
6
        }
7
    },
8
    {
9
        "data": {
10
            "text": "Health and Wellness Benefits: We care about your well-being and offer gym memberships, on-site yoga classes, and comprehensive health insurance."
11
        }
12
    },
13
]
14
15
# The user query
16
message = "Are there fitness-related benefits?"
17
18
# Generate the response
19
res_v2 = co_v2.chat(
20
    model="command-a-03-2025",
21
    messages=[{"role": "user", "content": message}],
22
    documents=documents_v2,
23
)
24
25
print(res_v2.message.content[0].text)

1
documents_v2 = [
2
    # List of objects with data string
3
    {
4
        "id": "123",
5
        "data": "I love penguins. they are fluffy",
6
    },
7
    # List of objects with data object
8
    {
9
        "id": "456",
10
        "data": {
11
            "text": "I love penguins. they are fluffy",
12
            "author": "Abdullah",
13
            "create_date": "09021989",
14
        },
15
    },
16
    # List of strings
17
    "just a string",
18
]

1
# Yes, there are fitness-related benefits. We offer gym memberships, on-site yoga classes, and comprehensive health insurance.
2
3
print(res_v1.citations)
4
print(res_v1.documents)

1
# Yes, we offer gym memberships, on-site yoga classes, and comprehensive health insurance.
2
3
print(res_v2.message.citations)

1
res_v1 = co_v1.chat(
2
    message="who won euro 2024",
3
    connectors=[{"id": "web-search"}],
4
)
5
6
print(res_v1.text)

1
# Any search engine can be used. This example uses the Tavily API.
2
from tavily import TavilyClient
3
4
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
5
6
7
# Create a web search function
8
def web_search(queries: list[str]) -> list[dict]:
9
10
    documents = []
11
12
    for query in queries:
13
        response = tavily_client.search(query, max_results=2)
14
15
        results = [
16
            {
17
                "title": r["title"],
18
                "content": r["content"],
19
                "url": r["url"],
20
            }
21
            for r in response["results"]
22
        ]
23
24
        for idx, result in enumerate(results):
25
            document = {"id": str(idx), "data": result}
26
            documents.append(document)
27
28
    return documents
29
30
31
# Define the web search tool
32
web_search_tool = [
33
    {
34
        "type": "function",
35
        "function": {
36
            "name": "web_search",
37
            "description": "Returns a list of relevant document snippets for a textual query retrieved from the internet",
38
            "parameters": {
39
                "type": "object",
40
                "properties": {
41
                    "queries": {
42
                        "type": "array",
43
                        "items": {"type": "string"},
44
                        "description": "a list of queries to search the internet with.",
45
                    }
46
                },
47
                "required": ["queries"],
48
            },
49
        },
50
    }
51
]
52
53
# The user query
54
query = "who won euro 2024"
55
56
# Define a system message to optimize search query generation
57
instructions = "Write a search query that will find helpful information for answering the user's question accurately. If you need more than one search query, write a list of search queries. If you decide that a search is very unlikely to find information that would be useful in constructing a response to the user, you should instead directly answer."
58
59
messages = [
60
    {"role": "system", "content": instructions},
61
    {"role": "user", "content": query},
62
]
63
64
model = "command-a-03-2025"
65
66
# Generate search queries (if any)
67
response = co_v2.chat(
68
    model=model, messages=messages, tools=web_search_tool
69
)
70
71
search_queries = []
72
73
while response.message.tool_calls:
74
75
    print("Tool plan:")
76
    print(response.message.tool_plan, "\n")
77
    print("Tool calls:")
78
    for tc in response.message.tool_calls:
79
        print(
80
            f"Tool name: {tc.function.name} | Parameters: {tc.function.arguments}"
81
        )
82
    print("=" * 50)
83
84
    messages.append(
85
        {
86
            "role": "assistant",
87
            "tool_calls": response.message.tool_calls,
88
            "tool_plan": response.message.tool_plan,
89
        }
90
    )
91
92
    # Step 3: Get tool results
93
    for idx, tc in enumerate(response.message.tool_calls):
94
        tool_result = web_search(**json.loads(tc.function.arguments))
95
        tool_content = []
96
        for data in tool_result:
97
            tool_content.append(
98
                {
99
                    "type": "document",
100
                    "document": {"data": json.dumps(data)},
101
                }
102
            )
103
            # Optional: add an "id" field in the "document" object, otherwise IDs are auto-generated
104
        messages.append(
105
            {
106
                "role": "tool",
107
                "tool_call_id": tc.id,
108
                "content": tool_content,
109
            }
110
        )
111
112
    # Step 4: Generate response and citations
113
    response = co_v2.chat(
114
        model=model, messages=messages, tools=web_search_tool
115
    )
116
117
print(response.message.content[0].text)

1
message = "Are there fitness-related benefits?"
2
3
res_v1 = co_v1.chat_stream(
4
    model="command-a-03-2025",
5
    message=message,
6
    documents=documents_v1,
7
)
8
9
for chunk in res_v1:
10
    if chunk.event_type == "text-generation":
11
        print(chunk.text, end="")
12
    if chunk.event_type == "citation-generation":
13
        print(f"\n{chunk.citations}")

1
message = "Are there fitness-related benefits?"
2
3
messages = [{"role": "user", "content": message}]
4
5
res_v2 = co_v2.chat_stream(
6
    model="command-a-03-2025",
7
    messages=messages,
8
    documents=documents_v2,
9
)
10
11
for chunk in res_v2:
12
    if chunk:
13
        if chunk.type == "content-delta":
14
            print(chunk.delta.message.content.text, end="")
15
        if chunk.type == "citation-start":
16
            print(f"\n{chunk.delta.message.citations}")

1
def get_weather(location):
2
    return {"temperature": "20C"}
3
4
5
functions_map = {"get_weather": get_weather}
6
7
tools_v1 = [
8
    {
9
        "name": "get_weather",
10
        "description": "Gets the weather of a given location",
11
        "parameter_definitions": {
12
            "location": {
13
                "description": "The location to get weather, example: San Francisco, CA",
14
                "type": "str",
15
                "required": True,
16
            }
17
        },
18
    },
19
]

1
def get_weather(location):
2
    return [{"temperature": "20C"}]
3
    # You can return a list of objects e.g. [{"url": "abc.com", "text": "..."}, {"url": "xyz.com", "text": "..."}]
4
5
6
functions_map = {"get_weather": get_weather}
7
8
tools_v2 = [
9
    {
10
        "type": "function",
11
        "function": {
12
            "name": "get_weather",
13
            "description": "gets the weather of a given location",
14
            "parameters": {
15
                "type": "object",
16
                "properties": {
17
                    "location": {
18
                        "type": "string",
19
                        "description": "the location to get weather, example: San Fransisco, CA",
20
                    }
21
                },
22
                "required": ["location"],
23
            },
24
        },
25
    },
26
]

1
message = "What's the weather in Toronto?"
2
3
res_v1 = co_v1.chat(
4
    model="command-a-03-2025", message=message, tools=tools_v1
5
)
6
7
print(res_v1.tool_calls)

1
messages = [
2
    {"role": "user", "content": "What's the weather in Toronto?"}
3
]
4
5
res_v2 = co_v2.chat(
6
    model="command-a-03-2025", messages=messages, tools=tools_v2
7
)
8
9
if res_v2.message.tool_calls:
10
    messages.append(
11
        {
12
            "role": "assistant",
13
            "tool_calls": res_v2.message.tool_calls,
14
            "tool_plan": res_v2.message.tool_plan,
15
        }
16
    )
17
18
    print(res_v2.message.tool_calls)

1
tool_results = [
2
    {
3
        "call": {
4
            "name": "<tool name>",
5
            "parameters": {"<param name>": "<param value>"},
6
        },
7
        "outputs": [{"<key>": "<value>"}],
8
    },
9
]

1
messages = [
2
    {
3
        "role": "tool",
4
        "tool_call_id": "123",
5
        "content": [
6
            {
7
                "type": "document",
8
                "document": {
9
                    "id": "123",
10
                    "data": {"<key>": "<value>"},
11
                },
12
            }
13
        ],
14
    }
15
]

1
tool_content_v1 = []
2
if res_v1.tool_calls:
3
    for tc in res_v1.tool_calls:
4
        tool_call = {"name": tc.name, "parameters": tc.parameters}
5
        tool_result = functions_map[tc.name](**tc.parameters)
6
        tool_content_v1.append(
7
            {"call": tool_call, "outputs": [tool_result]}
8
        )
9
10
res_v1 = co_v1.chat(
11
    model="command-a-03-2025",
12
    message="",
13
    tools=tools_v1,
14
    tool_results=tool_content_v1,
15
    chat_history=res_v1.chat_history,
16
)
17
18
print(res_v1.text)

1
if res_v2.message.tool_calls:
2
    for tc in res_v2.message.tool_calls:
3
        tool_result = functions_map[tc.function.name](
4
            **json.loads(tc.function.arguments)
5
        )
6
        tool_content_v2 = []
7
        for data in tool_result:
8
            tool_content_v2.append(
9
                {
10
                    "type": "document",
11
                    "document": {"data": json.dumps(data)},
12
                }
13
            )
14
            # Optional: add an "id" field in the "document" object, otherwise IDs are auto-generated
15
        messages.append(
16
            {
17
                "role": "tool",
18
                "tool_call_id": tc.id,
19
                "content": tool_content_v2,
20
            }
21
        )
22
23
res_v2 = co_v2.chat(
24
    model="command-a-03-2025", messages=messages, tools=tools_v2
25
)
26
27
print(res_v2.message.content[0].text)

1
print(res_v1.citations)
2
print(res_v1.documents)

1
print(res_v2.message.citations)

1
tool_content_v1 = []
2
if res_v1.tool_calls:
3
    for tc in res_v1.tool_calls:
4
        tool_call = {"name": tc.name, "parameters": tc.parameters}
5
        tool_result = functions_map[tc.name](**tc.parameters)
6
        tool_content_v1.append(
7
            {"call": tool_call, "outputs": [tool_result]}
8
        )
9
10
res_v1 = co_v1.chat_stream(
11
    message="",
12
    tools=tools_v1,
13
    tool_results=tool_content_v1,
14
    chat_history=res_v1.chat_history,
15
)
16
17
for chunk in res_v1:
18
    if chunk.event_type == "text-generation":
19
        print(chunk.text, end="")
20
    if chunk.event_type == "citation-generation":
21
        print(f"\n{chunk.citations}")

1
if res_v2.message.tool_calls:
2
    for tc in res_v2.message.tool_calls:
3
        tool_result = functions_map[tc.function.name](
4
            **json.loads(tc.function.arguments)
5
        )
6
        tool_content_v2 = []
7
        for data in tool_result:
8
            tool_content_v2.append(
9
                {
10
                    "type": "document",
11
                    "document": {"data": json.dumps(data)},
12
                }
13
            )
14
            # Optional: add an "id" field in the "document" object, otherwise IDs are auto-generated
15
        messages.append(
16
            {
17
                "role": "tool",
18
                "tool_call_id": tc.id,
19
                "content": tool_content_v2,
20
            }
21
        )
22
23
res_v2 = co_v2.chat_stream(
24
    model="command-a-03-2025", messages=messages, tools=tools_v2
25
)
26
27
for chunk in res_v2:
28
    if chunk:
29
        if chunk.type == "content-delta":
30
            print(chunk.delta.message.content.text, end="")
31
        elif chunk.type == "citation-start":
32
            print(f"\n{chunk.delta.message.citations}")