Mastering Function Calling: Connecting GPT-5 to Your Internal REST APIs

// tools/orderSchema.ts

export const orderTools = [
  {
    type: "function" as const,
    function: {
      name: "get_order_status",
      // GPT-5 reads this description to decide when to call this function
      description:
        "Retrieve the current status and shipping details for a customer order. Use this when the user asks about an order, delivery, or shipment.",
      parameters: {
        type: "object",
        properties: {
          order_id: {
            type: "string",
            // Enum narrows the model's output and reduces hallucinated IDs
            description: "The order ID in format ORD-XXXXXXXX (e.g. ORD-00293847)",
          },
          include_history: {
            type: "boolean",
            description: "If true, returns full status history. Defaults to false.",
          },
        },
        required: ["order_id"],
      },
    },
  },
  {
    type: "function" as const,
    function: {
      name: "search_products",
      description:
        "Search the internal product catalog by keyword, category, or SKU. Use when user asks about product availability, pricing, or specifications.",
      parameters: {
        type: "object",
        properties: {
          query: {
            type: "string",
            description: "Search keyword or product name",
          },
          category: {
            type: "string",
            enum: ["electronics", "apparel", "home", "sports"],
            description: "Optional category filter",
          },
          limit: {
            type: "integer",
            description: "Max results to return (1–20). Defaults to 5.",
          },
        },
        required: ["query"],
      },
    },
  },
];

// lib/chat.ts
import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

export async function runChatTurn(
  messages: OpenAI.Chat.ChatCompletionMessageParam[],
  tools: OpenAI.Chat.ChatCompletionTool[]
): Promise<OpenAI.Chat.ChatCompletion> {
  return client.chat.completions.create({
    model: "gpt-5",
    messages,
    tools,
    // "auto" lets the model decide; "required" forces a tool call every turn
    tool_choice: "auto",
    // Parallel calls let GPT-5 batch multiple function calls in one response
    parallel_tool_calls: true,
  });
}

// index.ts
import { orderTools } from "./tools/orderSchema";
import { runChatTurn } from "./lib/chat";

const messages = [
  {
    role: "system" as const,
    content:
      "You are a customer support assistant. Use the provided tools to answer questions about orders and products. Never make up order statuses.",
  },
  {
    role: "user" as const,
    content: "What's the status of my order ORD-00293847? Does it include tracking?",
  },
];

const response = await runChatTurn(messages, orderTools);
const message = response.choices[0].message;

console.log("Finish reason:", response.choices[0].finish_reason);
// "tool_calls" means the model wants to call a function
// "stop" means it responded directly with text

// lib/apiClient.ts

interface OrderStatus {
  order_id: string;
  status: "processing" | "shipped" | "delivered" | "cancelled";
  tracking_number?: string;
  estimated_delivery?: string;
  history?: { timestamp: string; status: string }[];
}

export async function getOrderStatus(
  orderId: string,
  includeHistory = false
): Promise<OrderStatus> {
  const url = new URL(`${process.env.INTERNAL_API_BASE}/orders/${orderId}`);
  if (includeHistory) url.searchParams.set("history", "true");

  const res = await fetch(url.toString(), {
    headers: {
      // Your internal API auth — never expose this to the client
      Authorization: `Bearer ${process.env.INTERNAL_API_SECRET}`,
      "Content-Type": "application/json",
    },
    // Abort if the internal API is slow — don't let it hang the LLM response
    signal: AbortSignal.timeout(5000),
  });

  if (!res.ok) {
    // Return a meaningful error string — the model will relay it to the user
    throw new Error(`Order API returned ${res.status}: ${await res.text()}`);
  }

  return res.json();
}

// lib/toolDispatcher.ts
import { getOrderStatus } from "./apiClient";

type ToolResult = string; // OpenAI tool results must be strings (JSON-encoded)

export async function dispatchToolCall(
  name: string,
  args: Record<string, unknown>
): Promise<ToolResult> {
  switch (name) {
    case "get_order_status": {
      const result = await getOrderStatus(
        args.order_id as string,
        (args.include_history as boolean) ?? false
      );
      // Stringify — the model reads this as context for its next response
      return JSON.stringify(result);
    }

    case "search_products": {
      // Wire your product search endpoint here
      const result = await searchProducts(
        args.query as string,
        args.category as string | undefined,
        (args.limit as number) ?? 5
      );
      return JSON.stringify(result);
    }

    default:
      // Fail loudly — unknown tool names indicate a schema/code mismatch
      throw new Error(`Unknown tool: ${name}`);
  }
}

// Complete the agentic loop
import { dispatchToolCall } from "./lib/toolDispatcher";
import type OpenAI from "openai";

async function agentLoop(
  initialMessages: OpenAI.Chat.ChatCompletionMessageParam[],
  tools: OpenAI.Chat.ChatCompletionTool[]
) {
  let messages = [...initialMessages];

  while (true) {
    const response = await runChatTurn(messages, tools);
    const choice = response.choices[0];

    // Model responded with text — we're done
    if (choice.finish_reason === "stop") {
      return choice.message.content;
    }

    // Model wants tool calls — execute them all (possibly in parallel)
    if (choice.finish_reason === "tool_calls" && choice.message.tool_calls) {
      // Append the assistant's tool_call message to history
      messages.push(choice.message);

      // Execute all requested tool calls concurrently
      const toolResults = await Promise.all(
        choice.message.tool_calls.map(async (toolCall) => {
          let result: string;

          try {
            result = await dispatchToolCall(
              toolCall.function.name,
              JSON.parse(toolCall.function.arguments)
            );
          } catch (err) {
            // Surface errors to the model so it can tell the user gracefully
            result = JSON.stringify({ error: (err as Error).message });
          }

          return {
            role: "tool" as const,
            tool_call_id: toolCall.id, // Must match the ID from the request
            content: result,
          };
        })
      );

      // Append all results before the next turn
      messages.push(...toolResults);

      // Loop — model will now generate a response using the tool results
      continue;
    }

    // Unexpected finish reason
    throw new Error(`Unexpected finish_reason: ${choice.finish_reason}`);
  }
}

// Run it
const finalResponse = await agentLoop(messages, orderTools);
console.log(finalResponse);
// → "Your order ORD-00293847 has shipped. Tracking number: 1Z999AA10123456784.
//    Estimated delivery: February 24. Would you like the full status history?"

# Smoke test with a real user query
npx ts-node index.ts

// Should gracefully surface the API error to the user
const badMessages = [
  ...systemMessage,
  { role: "user" as const, content: "Check order ORD-99999999" },
];

const result = await agentLoop(badMessages, orderTools);
// → "I wasn't able to find order ORD-99999999. Please double-check the ID
//    and try again, or contact support if the issue persists."