Completions V1 is Deprecated: This tutorial now uses the V2 API. If you’re using V1 (
/ai/v1/chat/completions), please migrate to V2 for better performance and intelligent routing.View V2 Guide | Migration StepsPrerequisites
Before starting, ensure you have:- A Gloo AI Studio account
- Your API key from the API Credentials page
- Authentication setup - Complete the Authentication Tutorial first
The Completions API with tool use requires an API key for authentication. If you haven’t set up authentication yet, follow the Authentication Tutorial.
Step 1: Define Your Tool Schema
The first step is to define a function schema that describes the structured output you want. This tells the AI exactly what format to return:{
"tools": [
{
"type": "function",
"function": {
"name": "create_growth_plan",
"description": "Creates a structured personal growth plan with a title and a series of actionable steps.",
"parameters": {
"type": "object",
"properties": {
"goal_title": {
"type": "string",
"description": "A concise, encouraging title for the user's goal."
},
"steps": {
"type": "array",
"description": "A list of concrete steps the user should take.",
"items": {
"type": "object",
"properties": {
"step_number": { "type": "integer" },
"action": {
"type": "string",
"description": "The specific, actionable task for this step."
},
"timeline": {
"type": "string",
"description": "A suggested timeframe for this step (e.g., 'Week 1-2')."
}
},
"required": ["step_number", "action", "timeline"]
}
}
},
"required": ["goal_title", "steps"]
}
}
}
]
}
Step 2: Make the API Call
Now make the API request with the tool definition and settool_choice: "required" to force the AI to use your tool:
{
"auto_routing": true,
"messages": [
{
"role": "user",
"content": "I want to grow in my faith."
}
],
"tools": [
// ... The tool definition from Step 1 goes here ...
],
"tool_choice": "required"
}
Auto-Routing: Setting
auto_routing: true lets Gloo AI automatically select the optimal model for your tool use request. This is the recommended V2 approach. You can also specify a direct model like "model": "gloo-anthropic-claude-sonnet-4.5" if you need explicit control.Example Response
The API will return structured data in thetool_calls array:
{
"id": "chatcmpl-ecc49558",
"choices": [
{
"finish_reason": "tool_calls",
"index": 0,
"message": {
"content": null,
"role": "assistant",
"tool_calls": [
{
"id": "tooluse_c0lmjtOJSlOYQZPBsp4biQ",
"function": {
"arguments": "{\"goal_title\": \"Growing Deeper in Faith\", \"steps\": [{\"step_number\": 1, \"action\": \"Establish a consistent daily quiet time with God through prayer and Bible reading, starting with 10-15 minutes each morning\", \"timeline\": \"Week 1-2\"}, {\"step_number\": 2, \"action\": \"Choose a Bible reading plan or devotional to provide structure for your study time\", \"timeline\": \"Week 2-3\"}, {\"step_number\": 3, \"action\": \"Find a local church community or small group where you can worship, learn, and build relationships with other believers\", \"timeline\": \"Week 3-4\"}, {\"step_number\": 4, \"action\": \"Begin journaling your prayers, thoughts, and insights from Scripture to track your spiritual growth\", \"timeline\": \"Week 4-5\"}, {\"step_number\": 5, \"action\": \"Look for opportunities to serve others in your community or church as a way to live out your faith\", \"timeline\": \"Month 2\"}, {\"step_number\": 6, \"action\": \"Seek out a mentor or accountability partner who can encourage you and help you grow in your walk with God\", \"timeline\": \"Month 2-3\"}]}",
"name": "create_growth_plan"
},
"type": "function"
}
]
}
}
],
"created": 1755118870,
"model": "gloo-anthropic-claude-sonnet-4.5",
"object": "chat.completion",
"usage": {
"completion_tokens": 391,
"prompt_tokens": 1631,
"total_tokens": 2022
}
}
arguments field contains a JSON string that matches your tool schema perfectly!
Complete Examples
The following examples combine authentication, making the API call with tool use, and parsing the structured response into a complete, runnable script for each language. You’ll want to first set up your environment variables in either an.env file:
GLOO_API_KEY=YOUR_API_KEY
export GLOO_API_KEY="your_actual_api_key_here"
import requests
import json
import os
from dotenv import load_dotenv
# Load environment variables from .env file
load_dotenv()
# --- Configuration ---
# It's recommended to load your API key from an environment variable
API_KEY = os.getenv("GLOO_API_KEY", "YOUR_API_KEY")
API_URL = "https://platform.ai.gloo.com/ai/v2/chat/completions"
def create_goal_setting_request(user_goal):
"""Creates a goal-setting request with tool use."""
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
payload = {
"auto_routing": True,
"messages": [{"role": "user", "content": user_goal}],
"tools": [
{
"type": "function",
"function": {
"name": "create_growth_plan",
"description": "Creates a structured personal growth plan with a title and a series of actionable steps.",
"parameters": {
"type": "object",
"properties": {
"goal_title": {
"type": "string",
"description": "A concise, encouraging title for the user's goal."
},
"steps": {
"type": "array",
"description": "A list of concrete steps the user should take.",
"items": {
"type": "object",
"properties": {
"step_number": {"type": "integer"},
"action": {
"type": "string",
"description": "The specific, actionable task for this step."
},
"timeline": {
"type": "string",
"description": "A suggested timeframe for this step (e.g., 'Week 1-2')."
}
},
"required": ["step_number", "action", "timeline"]
}
}
},
"required": ["goal_title", "steps"]
}
}
}
],
"tool_choice": "required"
}
response = requests.post(API_URL, headers=headers, json=payload)
response.raise_for_status()
return response.json()
def parse_growth_plan(api_response):
"""Parses the API response and extracts the structured growth plan."""
try:
tool_call = api_response['choices'][0]['message']['tool_calls'][0]
function_args = json.loads(tool_call['function']['arguments'])
return function_args
except (KeyError, IndexError, json.JSONDecodeError) as e:
raise ValueError(f"Failed to parse growth plan: {e}")
def display_growth_plan(growth_plan):
"""Displays the growth plan in a user-friendly format."""
print(f"\n🎯 {growth_plan['goal_title']}")
print("=" * (len(growth_plan['goal_title']) + 4))
for step in growth_plan['steps']:
print(f"\n{step['step_number']}. {step['action']}")
print(f" ⏰ Timeline: {step['timeline']}")
# --- Main Execution ---
if __name__ == "__main__":
try:
user_goal = "I want to grow in my faith."
print(f"Creating growth plan for: '{user_goal}'")
# Make API call with tool use
response = create_goal_setting_request(user_goal)
# Parse the structured response
growth_plan = parse_growth_plan(response)
# Display the results
display_growth_plan(growth_plan)
# Also show raw JSON for developers
print(f"\n📊 Raw JSON output:")
print(json.dumps(growth_plan, indent=2))
except requests.exceptions.HTTPError as err:
print(f"An HTTP error occurred: {err}")
except Exception as err:
print(f"An error occurred: {err}")
// Load environment variables from .env file
require('dotenv').config();
const axios = require('axios');
// --- Configuration ---
const API_KEY = process.env.GLOO_API_KEY || "YOUR_API_KEY";
const API_URL = "https://platform.ai.gloo.com/ai/v2/chat/completions";
async function createGoalSettingRequest(userGoal) {
const payload = {
auto_routing: true,
messages: [{ role: "user", content: userGoal }],
tools: [
{
type: "function",
function: {
name: "create_growth_plan",
description: "Creates a structured personal growth plan with a title and a series of actionable steps.",
parameters: {
type: "object",
properties: {
goal_title: {
type: "string",
description: "A concise, encouraging title for the user's goal."
},
steps: {
type: "array",
description: "A list of concrete steps the user should take.",
items: {
type: "object",
properties: {
step_number: { type: "integer" },
action: {
type: "string",
description: "The specific, actionable task for this step."
},
timeline: {
type: "string",
description: "A suggested timeframe for this step (e.g., 'Week 1-2')."
}
},
required: ["step_number", "action", "timeline"]
}
}
},
required: ["goal_title", "steps"]
}
}
}
],
tool_choice: "required"
};
const response = await axios.post(API_URL, payload, {
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
},
});
return response.data;
}
function parseGrowthPlan(apiResponse) {
try {
const toolCall = apiResponse.choices[0].message.tool_calls[0];
return JSON.parse(toolCall.function.arguments);
} catch (error) {
throw new Error(`Failed to parse growth plan: ${error.message}`);
}
}
function displayGrowthPlan(growthPlan) {
console.log(`\n🎯 ${growthPlan.goal_title}`);
console.log("=".repeat(growthPlan.goal_title.length + 4));
growthPlan.steps.forEach(step => {
console.log(`\n${step.step_number}. ${step.action}`);
console.log(` ⏰ Timeline: ${step.timeline}`);
});
}
// --- Main Execution ---
async function main() {
try {
const userGoal = "I want to grow in my faith.";
console.log(`Creating growth plan for: '${userGoal}'`);
// Make API call with tool use
const response = await createGoalSettingRequest(userGoal);
// Parse the structured response
const growthPlan = parseGrowthPlan(response);
// Display the results
displayGrowthPlan(growthPlan);
// Also show raw JSON for developers
console.log(`\n📊 Raw JSON output:`);
console.log(JSON.stringify(growthPlan, null, 2));
} catch (error) {
console.error("An error occurred:", error.response ? error.response.data : error.message);
}
}
main();
import axios from 'axios';
import * as dotenv from 'dotenv';
// Load environment variables from .env file
dotenv.config();
// Type definitions
interface GrowthStep {
step_number: number;
action: string;
timeline: string;
}
interface GrowthPlan {
goal_title: string;
steps: GrowthStep[];
}
interface ToolCall {
id: string;
type: string;
function: {
name: string;
arguments: string;
};
}
interface ApiResponse {
choices: Array<{
message: {
tool_calls: ToolCall[];
};
}>;
}
// --- Configuration ---
const API_KEY = process.env.GLOO_API_KEY || "YOUR_API_KEY";
const API_URL = "https://platform.ai.gloo.com/ai/v2/chat/completions";
async function createGoalSettingRequest(userGoal: string): Promise<ApiResponse> {
const payload = {
auto_routing: true,
messages: [{ role: "user", content: userGoal }],
tools: [
{
type: "function",
function: {
name: "create_growth_plan",
description: "Creates a structured personal growth plan with a title and a series of actionable steps.",
parameters: {
type: "object",
properties: {
goal_title: {
type: "string",
description: "A concise, encouraging title for the user's goal."
},
steps: {
type: "array",
description: "A list of concrete steps the user should take.",
items: {
type: "object",
properties: {
step_number: { type: "integer" },
action: {
type: "string",
description: "The specific, actionable task for this step."
},
timeline: {
type: "string",
description: "A suggested timeframe for this step (e.g., 'Week 1-2')."
}
},
required: ["step_number", "action", "timeline"]
}
}
},
required: ["goal_title", "steps"]
}
}
}
],
tool_choice: "required"
};
const response = await axios.post<ApiResponse>(API_URL, payload, {
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
},
});
return response.data;
}
function parseGrowthPlan(apiResponse: ApiResponse): GrowthPlan {
try {
const toolCall = apiResponse.choices[0].message.tool_calls[0];
return JSON.parse(toolCall.function.arguments) as GrowthPlan;
} catch (error: any) {
throw new Error(`Failed to parse growth plan: ${error.message}`);
}
}
function displayGrowthPlan(growthPlan: GrowthPlan): void {
console.log(`\n🎯 ${growthPlan.goal_title}`);
console.log("=".repeat(growthPlan.goal_title.length + 4));
growthPlan.steps.forEach(step => {
console.log(`\n${step.step_number}. ${step.action}`);
console.log(` ⏰ Timeline: ${step.timeline}`);
});
}
// --- Main Execution ---
async function main(): Promise<void> {
try {
const userGoal = "I want to grow in my faith.";
console.log(`Creating growth plan for: '${userGoal}'`);
// Make API call with tool use
const response = await createGoalSettingRequest(userGoal);
// Parse the structured response
const growthPlan = parseGrowthPlan(response);
// Display the results
displayGrowthPlan(growthPlan);
// Also show raw JSON for developers
console.log(`\n📊 Raw JSON output:`);
console.log(JSON.stringify(growthPlan, null, 2));
} catch (error: any) {
console.error("An error occurred:", error.response ? error.response.data : error.message);
}
}
main();
<?php
require_once 'vendor/autoload.php';
// Load environment variables from .env file
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
// --- Configuration ---
$API_KEY = $_ENV['GLOO_API_KEY'] ?? 'YOUR_API_KEY';
$API_URL = 'https://platform.ai.gloo.com/ai/v2/chat/completions';
// Validate credentials
if ($API_KEY === 'YOUR_API_KEY' || empty($API_KEY)) {
echo "Error: GLOO_API_KEY must be set\n";
echo "Either:\n";
echo "1. Create a .env file with your credentials:\n";
echo " GLOO_API_KEY=your_api_key_here\n";
echo "2. Export them as environment variables:\n";
echo " export GLOO_API_KEY=\"your_api_key_here\"\n";
exit(1);
}
function createGoalSettingRequest($userGoal, $apiUrl, $apiKey) {
$tools = [
[
'type' => 'function',
'function' => [
'name' => 'create_growth_plan',
'description' => 'Creates a structured personal growth plan with a title and a series of actionable steps.',
'parameters' => [
'type' => 'object',
'properties' => [
'goal_title' => [
'type' => 'string',
'description' => 'A concise, encouraging title for the user\'s goal.'
],
'steps' => [
'type' => 'array',
'description' => 'A list of concrete steps the user should take.',
'items' => [
'type' => 'object',
'properties' => [
'step_number' => ['type' => 'integer'],
'action' => [
'type' => 'string',
'description' => 'The specific, actionable task for this step.'
],
'timeline' => [
'type' => 'string',
'description' => 'A suggested timeframe for this step (e.g., \'Week 1-2\').'
]
],
'required' => ['step_number', 'action', 'timeline']
]
]
],
'required' => ['goal_title', 'steps']
]
]
]
];
$payload = json_encode([
'auto_routing' => true,
'messages' => [['role' => 'user', 'content' => $userGoal]],
'tools' => $tools,
'tool_choice' => 'required'
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $apiKey,
]);
$result = curl_exec($ch);
if (curl_errno($ch)) throw new Exception(curl_error($ch));
curl_close($ch);
return json_decode($result, true);
}
function parseGrowthPlan($apiResponse) {
try {
$toolCall = $apiResponse['choices'][0]['message']['tool_calls'][0];
return json_decode($toolCall['function']['arguments'], true);
} catch (Exception $e) {
throw new Exception("Failed to parse growth plan: " . $e->getMessage());
}
}
function displayGrowthPlan($growthPlan) {
echo "\n🎯 " . $growthPlan['goal_title'] . "\n";
echo str_repeat("=", strlen($growthPlan['goal_title']) + 4) . "\n";
foreach ($growthPlan['steps'] as $step) {
echo "\n" . $step['step_number'] . ". " . $step['action'] . "\n";
echo " ⏰ Timeline: " . $step['timeline'] . "\n";
}
}
// --- Main Execution ---
try {
$userGoal = "I want to grow in my faith.";
echo "Creating growth plan for: '$userGoal'\n";
// Make API call with tool use
$response = createGoalSettingRequest($userGoal, $API_URL, $API_KEY);
// Parse the structured response
$growthPlan = parseGrowthPlan($response);
// Display the results
displayGrowthPlan($growthPlan);
// Also show raw JSON for developers
echo "\n📊 Raw JSON output:\n";
echo json_encode($growthPlan, JSON_PRETTY_PRINT) . "\n";
} catch (Exception $e) {
echo 'Error: ' . $e->getMessage() . "\n";
}
?>
package main
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
"os"
"strings"
"github.com/joho/godotenv"
)
// --- Configuration ---
var (
apiKey string
apiURL = "https://platform.ai.gloo.com/ai/v2/chat/completions"
)
// --- Data Structures ---
type GrowthStep struct {
StepNumber int `json:"step_number"`
Action string `json:"action"`
Timeline string `json:"timeline"`
}
type GrowthPlan struct {
GoalTitle string `json:"goal_title"`
Steps []GrowthStep `json:"steps"`
}
type ToolCall struct {
ID string `json:"id"`
Type string `json:"type"`
Function struct {
Name string `json:"name"`
Arguments string `json:"arguments"`
} `json:"function"`
}
type ApiResponse struct {
Choices []struct {
Message struct {
ToolCalls []ToolCall `json:"tool_calls"`
} `json:"message"`
} `json:"choices"`
}
// --- Function Definitions ---
func createGoalSettingRequest(userGoal string) (*ApiResponse, error) {
tools := []map[string]interface{}{
{
"type": "function",
"function": map[string]interface{}{
"name": "create_growth_plan",
"description": "Creates a structured personal growth plan with a title and a series of actionable steps.",
"parameters": map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"goal_title": map[string]interface{}{
"type": "string",
"description": "A concise, encouraging title for the user's goal.",
},
"steps": map[string]interface{}{
"type": "array",
"description": "A list of concrete steps the user should take.",
"items": map[string]interface{}{
"type": "object",
"properties": map[string]interface{}{
"step_number": map[string]string{"type": "integer"},
"action": map[string]string{
"type": "string",
"description": "The specific, actionable task for this step.",
},
"timeline": map[string]string{
"type": "string",
"description": "A suggested timeframe for this step (e.g., 'Week 1-2').",
},
},
"required": []string{"step_number", "action", "timeline"},
},
},
},
"required": []string{"goal_title", "steps"},
},
},
},
}
payload := map[string]interface{}{
"auto_routing": true,
"messages": []map[string]string{{"role": "user", "content": userGoal}},
"tools": tools,
"tool_choice": "required",
}
jsonPayload, _ := json.Marshal(payload)
req, err := http.NewRequest("POST", apiURL, bytes.NewBuffer(jsonPayload))
if err != nil {
return nil, err
}
req.Header.Add("Authorization", "Bearer "+apiKey)
req.Header.Add("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
if resp.StatusCode != http.StatusOK {
return nil, fmt.Errorf("API call failed: %s - %s", resp.Status, string(body))
}
var result ApiResponse
json.Unmarshal(body, &result)
return &result, nil
}
func parseGrowthPlan(apiResponse *ApiResponse) (*GrowthPlan, error) {
if len(apiResponse.Choices) == 0 || len(apiResponse.Choices[0].Message.ToolCalls) == 0 {
return nil, fmt.Errorf("no tool calls found in response")
}
toolCall := apiResponse.Choices[0].Message.ToolCalls[0]
var growthPlan GrowthPlan
if err := json.Unmarshal([]byte(toolCall.Function.Arguments), &growthPlan); err != nil {
return nil, fmt.Errorf("failed to parse growth plan: %v", err)
}
return &growthPlan, nil
}
func displayGrowthPlan(growthPlan *GrowthPlan) {
fmt.Printf("\n🎯 %s\n", growthPlan.GoalTitle)
fmt.Printf("%s\n", strings.Repeat("=", len(growthPlan.GoalTitle)+4))
for _, step := range growthPlan.Steps {
fmt.Printf("\n%d. %s\n", step.StepNumber, step.Action)
fmt.Printf(" ⏰ Timeline: %s\n", step.Timeline)
}
}
// Helper to get environment variables
func getEnv(key, fallback string) string {
if value, ok := os.LookupEnv(key); ok {
return value
}
return fallback
}
// Initialize loads environment variables and validates configuration
func init() {
// Load environment variables from .env file if it exists
_ = godotenv.Load()
// Get credentials from environment
apiKey = getEnv("GLOO_API_KEY", "")
// Validate that credentials are provided
if apiKey == "" {
fmt.Println("Error: GLOO_API_KEY must be set")
fmt.Println("Either:")
fmt.Println("1. Create a .env file with your credentials:")
fmt.Println(" GLOO_API_KEY=your_api_key_here")
fmt.Println("2. Export them as environment variables:")
fmt.Println(" export GLOO_API_KEY=\"your_api_key_here\"")
os.Exit(1)
}
}
// --- Main Execution ---
func main() {
userGoal := "I want to grow in my faith."
fmt.Printf("Creating growth plan for: '%s'\n", userGoal)
// Make API call with tool use
response, err := createGoalSettingRequest(userGoal)
if err != nil {
fmt.Printf("Error creating growth plan: %v\n", err)
return
}
// Parse the structured response
growthPlan, err := parseGrowthPlan(response)
if err != nil {
fmt.Printf("Error parsing growth plan: %v\n", err)
return
}
// Display the results
displayGrowthPlan(growthPlan)
// Also show raw JSON for developers
fmt.Printf("\n📊 Raw JSON output:\n")
jsonBytes, _ := json.MarshalIndent(growthPlan, "", " ")
fmt.Printf("%s\n", string(jsonBytes))
}
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import com.google.gson.JsonArray;
import io.github.cdimascio.dotenv.Dotenv;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.List;
// --- Main Application Class ---
public class Main {
public static void main(String[] args) {
// Validate credentials before proceeding
if (!CompletionsToolUse.validateCredentials()) {
System.exit(1);
}
CompletionsToolUse toolUse = new CompletionsToolUse();
try {
String userGoal = "I want to grow in my faith.";
System.out.println("Creating growth plan for: '" + userGoal + "'");
// Make API call with tool use
ApiResponse response = toolUse.createGoalSettingRequest(userGoal);
// Parse the structured response
GrowthPlan growthPlan = toolUse.parseGrowthPlan(response);
// Display the results
toolUse.displayGrowthPlan(growthPlan);
// Also show raw JSON for developers
System.out.println("\n📊 Raw JSON output:");
System.out.println(toolUse.gson.toJson(growthPlan));
} catch (Exception e) {
e.printStackTrace();
}
}
}
// --- Completions Tool Use Class ---
class CompletionsToolUse {
// Load environment variables from .env file if it exists
private static final Dotenv dotenv = Dotenv.configure()
.ignoreIfMissing()
.load();
private static final String API_KEY = dotenv.get("GLOO_API_KEY", "YOUR_API_KEY");
private static final String API_URL = "https://platform.ai.gloo.com/ai/v2/chat/completions";
private final HttpClient httpClient = HttpClient.newHttpClient();
public final Gson gson = new Gson();
// Validate that credentials are provided
public static boolean validateCredentials() {
if ("YOUR_API_KEY".equals(API_KEY) || API_KEY == null || API_KEY.trim().isEmpty()) {
System.err.println("Error: GLOO_API_KEY must be set");
System.err.println("Either:");
System.err.println("1. Create a .env file with your credentials:");
System.err.println(" GLOO_API_KEY=your_api_key_here");
System.err.println("2. Export them as environment variables:");
System.err.println(" export GLOO_API_KEY=\"your_api_key_here\"");
return false;
}
return true;
}
// --- Data Classes ---
static class GrowthStep {
int step_number;
String action;
String timeline;
}
static class GrowthPlan {
String goal_title;
List<GrowthStep> steps;
}
static class ToolCall {
String id;
String type;
Function function;
static class Function {
String name;
String arguments;
}
}
static class ApiResponse {
List<Choice> choices;
static class Choice {
Message message;
static class Message {
List<ToolCall> tool_calls;
}
}
}
// --- API Methods ---
public ApiResponse createGoalSettingRequest(String userGoal) throws IOException, InterruptedException {
// Create the tool definition using JsonObject for proper structure
JsonObject toolSchema = new JsonObject();
toolSchema.addProperty("type", "function");
JsonObject function = new JsonObject();
function.addProperty("name", "create_growth_plan");
function.addProperty("description", "Creates a structured personal growth plan with a title and a series of actionable steps.");
JsonObject parameters = new JsonObject();
parameters.addProperty("type", "object");
JsonObject properties = new JsonObject();
JsonObject goalTitle = new JsonObject();
goalTitle.addProperty("type", "string");
goalTitle.addProperty("description", "A concise, encouraging title for the user's goal.");
properties.add("goal_title", goalTitle);
JsonObject steps = new JsonObject();
steps.addProperty("type", "array");
steps.addProperty("description", "A list of concrete steps the user should take.");
JsonObject items = new JsonObject();
items.addProperty("type", "object");
JsonObject itemProperties = new JsonObject();
JsonObject stepNumber = new JsonObject();
stepNumber.addProperty("type", "integer");
itemProperties.add("step_number", stepNumber);
JsonObject action = new JsonObject();
action.addProperty("type", "string");
action.addProperty("description", "The specific, actionable task for this step.");
itemProperties.add("action", action);
JsonObject timeline = new JsonObject();
timeline.addProperty("type", "string");
timeline.addProperty("description", "A suggested timeframe for this step (e.g., 'Week 1-2').");
itemProperties.add("timeline", timeline);
items.add("properties", itemProperties);
JsonArray required = new JsonArray();
required.add("step_number");
required.add("action");
required.add("timeline");
items.add("required", required);
steps.add("items", items);
properties.add("steps", steps);
parameters.add("properties", properties);
JsonArray requiredParams = new JsonArray();
requiredParams.add("goal_title");
requiredParams.add("steps");
parameters.add("required", requiredParams);
function.add("parameters", parameters);
toolSchema.add("function", function);
JsonArray tools = new JsonArray();
tools.add(toolSchema);
JsonObject message = new JsonObject();
message.addProperty("role", "user");
message.addProperty("content", userGoal);
JsonArray messages = new JsonArray();
messages.add(message);
JsonObject payload = new JsonObject();
payload.addProperty("auto_routing", true);
payload.add("messages", messages);
payload.add("tools", tools);
payload.addProperty("tool_choice", "required");
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(API_URL))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer " + API_KEY)
.POST(HttpRequest.BodyPublishers.ofString(gson.toJson(payload)))
.build();
HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 200) {
throw new IOException("API call failed: " + response.body());
}
return gson.fromJson(response.body(), ApiResponse.class);
}
public GrowthPlan parseGrowthPlan(ApiResponse apiResponse) {
try {
ToolCall toolCall = apiResponse.choices.get(0).message.tool_calls.get(0);
return gson.fromJson(toolCall.function.arguments, GrowthPlan.class);
} catch (Exception e) {
throw new RuntimeException("Failed to parse growth plan: " + e.getMessage(), e);
}
}
public void displayGrowthPlan(GrowthPlan growthPlan) {
System.out.println("\n🎯 " + growthPlan.goal_title);
System.out.println("=".repeat(growthPlan.goal_title.length() + 4));
for (GrowthStep step : growthPlan.steps) {
System.out.println("\n" + step.step_number + ". " + step.action);
System.out.println(" ⏰ Timeline: " + step.timeline);
}
}
}
Testing Your Implementation
To test any of the complete examples:- Set up your environment variables with your actual Gloo AI credentials
- Install dependencies according to each language’s requirements
- Run the script and observe the structured output
- Authenticate using your API key
- Make a tool-use API call with the goal “I want to grow in my faith”
- Parse the JSON response into a structured format
- Display the growth plan in a user-friendly format
- Show the raw JSON for developers
Key Benefits
This approach provides several advantages over simple chat completions:- Predictable Structure: The response always follows your defined schema
- Machine-Readable: Easy to parse and use in applications
- Type Safety: Clear data types for each field
- Validation: The API enforces your schema requirements
- Flexibility: Can adapt to any structured output needs
Working Code Sample
View Complete Code
Clone or browse the complete working examples for all 6 languages (JavaScript, TypeScript, Python, PHP, Go, Java) with setup instructions.
Next Steps
Now that you understand how to use tool use for structured output with V2, consider exploring:- Completions V2 Guide - Learn about auto-routing and model selection options
- Tool Use Guide - For more advanced tool use patterns and multi-step workflows
- Completions API Reference - Full API documentation
- Custom Schemas - Adapt this pattern for your specific use cases

