Tool Usage
cURL examples for calling built-in tools and defining custom function tools with the Agentaus API.
Using Built-in Tools
1
Submit a chat completion request with built-in tool definitions:
sh
curl -X POST https://xy-test.trellisdata.com.au/api/v1/chat/completions \
-H "Authorization: Bearer $AGENTAUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [{"role": "user", "content": "what is the weather today in canberra"}],
"stream": false,
"tools": [{"type": "agentaus_web_fetch"}, {"type": "agentaus_web_search"}]
}'2
You will receive output similar to this:
json
{
"choices": [
{
"finish_reason": "stop",
"index": 0,
"logprobs": null,
"message": {
"content": "Current weather in Canberra ...",
"refusal": null,
"role": "assistant",
"tool_calls": []
}
}
],
"created": 1782445600,
"id": "chatcmpl-1782445600",
"model": "agentaus",
"object": "chat.completion",
"usage": {
"input_tokens": 19060,
"output_tokens": 535
}
}Using Custom Function
1
Define your custom function (the actual function body) and declare it to the API with name, description, parameters, and required. All four fields are mandatory.
2
Submit a chat completion request with your custom tool definition:
sh
curl -X POST https://xy-test.trellisdata.com.au/api/v1/chat/completions \
-H "Authorization: Bearer $AGENTAUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [{"role": "user", "content": "What is the latest AUD to USD rate?"}],
"stream": false,
"tools": [
{
"type": "function",
"function": {
"name": "get_exchange_rate",
"description": "Get the exchange rate between two currencies",
"parameters": {
"type": "object",
"properties": {
"from": {"type": "string", "description": "Source currency code"},
"to": {"type": "string", "description": "Target currency code"}
},
"required": ["from", "to"]
}
}
}
],
"tool_choice": "auto"
}'3
You will receive output similar to this:
json
{
"choices": [
{
"finish_reason": "tool_calls",
"index": 0,
"logprobs": null,
"message": {
"content": null,
"role": "assistant",
"tool_calls": [
{
"function": {
"arguments": "{\"from\":\"AUD\",\"to\":\"USD\"}",
"name": "get_exchange_rate"
},
"id": "call_953bb8154bf90511",
"type": "function"
}
]
}
}
],
"created": 1782450600,
"id": "chatcmpl-1782450600",
"model": "agentaus",
"object": "chat.completion",
"usage": {
"input_tokens": 2387,
"output_tokens": 54
}
}4
From step 3, the model requested get_exchange_rate with from = "AUD" and to = "USD". Execute the function with those inputs and receive the result (e.g. {"rate": 0.67}).
5
Include the function result and send the full conversation back:
sh
curl -X POST https://xy-test.trellisdata.com.au/api/v1/chat/completions \
-H "Authorization: Bearer $AGENTAUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [
{"role": "user", "content": "What is the latest AUD to USD rate?"},
{"content": null, "role": "assistant", "tool_calls": [{"id": "call_953bb8154bf90511", "function": {"arguments": "{\"from\":\"AUD\",\"to\":\"USD\"}", "name": "get_exchange_rate"}, "type": "function"}]},
{"role": "tool", "tool_call_id": "call_953bb8154bf90511", "content": "{\"rate\": 0.67}"}
],
"stream": false,
"tools": [
{
"type": "function",
"function": {
"name": "get_exchange_rate",
"description": "Get the exchange rate between two currencies",
"parameters": {
"type": "object",
"properties": {
"from": {"type": "string", "description": "Source currency code"},
"to": {"type": "string", "description": "Target currency code"}
},
"required": ["from", "to"]
}
}
}
]
}'6
You will receive output similar to this:
json
{
"choices": [
{
"finish_reason": "stop",
"index": 0,
"logprobs": null,
"message": {
"content": "The most recent rate I retrieved is:\n\n**1 AUD ≈ 0.67 USD**\n\nPlease verify this figure independently (e.g., via your bank or a reputable financial news source) before making any decisions, as exchange rates can change rapidly.",
"refusal": null,
"role": "assistant",
"tool_calls": []
}
}
],
"created": 1782451181,
"id": "chatcmpl-1782451181",
"model": "agentaus",
"object": "chat.completion",
"usage": {
"input_tokens": 2450,
"output_tokens": 237
}
}