Cohere Tool Use & Agents (Core Workflow B)
Overview
Build multi-step tool-using agents with Cohere's Chat API v2. The model decides which tools to call, you execute them, and feed results back in a loop until the task is complete.
Prerequisites
- Completed
cohere-install-auth setup
- Understanding of
cohere-core-workflow-a (RAG)
- Command R7B or newer model (required for tool use)
Instructions
Step 1: Define Tools
import { CohereClientV2 } from 'cohere-ai';
const cohere = new CohereClientV2();
const tools = [
{
type: 'function' as const,
function: {
name: 'get_weather',
description: 'Get current weather for a city',
parameters: {
type: 'object' as const,
properties: {
city: { type: 'string', description: 'City name' },
unit: { type: 'string', enum: ['celsius', 'fahrenheit'], description: 'Temperature unit' },
},
required: ['city'],
},
},
},
{
type: 'function' as const,
function: {
name: 'search_database',
description: 'Search internal database for records',
parameters: {
type: 'object' as const,
properties: {
query: { type: 'string', description: 'Search query' },
limit: { type: 'number', description: 'Max results' },
},
required: ['query'],
},
},
},
];
Step 2: Implement Tool Executors
const toolExecutors: Record<string, (args: any) => Promise<string>> = {
get_weather: async ({ city, unit = 'celsius' }) => {
return JSON.stringify({
city,
temperature: unit === 'celsius' ? 22 : 72,
unit,
condition: 'partly cloudy',
});
},
search_database: async ({ query, limit = 5 }) => {
return JSON.stringify({
results: [
{ id: 1, title: `Result for: ${query}`, relevance: 0.95 },
],
total: 1,
});
},
};
Step 3: Single-Step Tool Use
async function singleStepToolUse(userMessage: string) {
const response = await cohere.chat({
model: 'command-a-03-2025',
messages: [{ role: 'user', content: userMessage }],
tools,
});
if (response.finishReason === 'TOOL_CALL') {
const toolCalls = response.message?.toolCalls ?? [];
const toolResults = await Promise.all(
toolCalls.map(async (tc) => {
const executor = toolExecutors[tc.function.name];
const args = JSON.parse(tc.function.arguments);
const result = await executor(args);
return {
call: tc,
outputs: [{ result }],
};
})
);
const finalResponse = await cohere.chat({
: ,
: [
{ : , : userMessage },
{ : , toolCalls },
{ : , : toolCalls[]., : toolResults[].[]. },
],
tools,
});
finalResponse.?.?.[]?. ?? ;
}
response.?.?.[]?. ?? ;
}
Step 4: Multi-Step Agent Loop
async function agentLoop(userMessage: string, maxSteps = 5) {
const messages: any[] = [{ role: 'user', content: userMessage }];
for (let step = 0; step < maxSteps; step++) {
const response = await cohere.chat({
model: 'command-a-03-2025',
messages,
tools,
});
if (response.finishReason !== 'TOOL_CALL') {
return response.message?.content?.[0]?.text ?? '';
}
const toolCalls = response.message?.toolCalls ?? [];
messages.push({ role: 'assistant', toolCalls });
for (const tc of toolCalls) {
const executor = toolExecutors[tc.function.name];
if (!executor) {
messages.push({ role: 'tool', : tc., : });
;
}
{
args = .(tc..);
result = (args);
messages.({ : , : tc., : result });
} (err) {
messages.({ : , : tc., : });
}
}
.();
}
;
}
answer = ();
.(answer);
Step 5: Force Tool Use
const response = await cohere.chat({
model: 'command-a-03-2025',
messages: [{ role: 'user', content: 'Look up the weather in Paris' }],
tools,
toolChoice: 'REQUIRED',
});
Step 6: Streaming Tool Use
async function streamWithTools(userMessage: string) {
const stream = await cohere.chatStream({
model: 'command-a-03-2025',
messages: [{ role: 'user', content: userMessage }],
tools,
});
const toolCalls: any[] = [];
for await (const event of stream) {
switch (event.type) {
case 'tool-call-start':
console.log(`Tool call: ${event.delta?.message?.toolCalls?.function?.name}`);
break;
case 'tool-call-delta':
break;
case 'content-delta':
process.stdout.write(event.delta?.message?.content?.text ?? '');
break;
}
}
}
Output
- Single-step tool calls with automatic execution
- Multi-step agent loop handling sequential reasoning
- Parallel tool execution for independent calls
- Streaming with tool-call events
Error Handling
| Error | Cause | Solution |
|---|
tool not found | Mismatched tool name | Verify tools array matches executors |
invalid arguments | Schema mismatch | Check tool parameter types |
| Infinite loop | Model keeps calling tools | Set maxSteps limit |
TOOL_CALL with no toolCalls | Edge case | Check response.message?.toolCalls length |
Resources
Next Steps
For common errors, see cohere-common-errors.
