How to Fix 'tool calling failure in production' in AutoGen (TypeScript)

When AutoGen throws tool calling failure in production, it usually means the model decided to call a tool, but your runtime could not execute that call cleanly. In TypeScript, this tends to show up when the tool schema, handler signature, or model config does not match what AutoGen expects.

In practice, this error appears after you’ve wired up AssistantAgent, registered tools, and moved from local testing to a real LLM provider. The failure is often not in the model itself; it’s in the contract between the generated tool call and your TypeScript function.

The Most Common Cause

The #1 cause is a mismatch between the tool definition and the actual function signature or return shape.

AutoGen sends structured arguments like JSON. If your tool expects positional parameters, returns a non-serializable value, or your schema does not match the implementation, you’ll get errors like:

• •Tool invocation failed
• •Error: tool calling failure in production
• •Invalid tool arguments
• •Cannot serialize tool result

Broken vs fixed pattern

// BROKEN
import { AssistantAgent } from "@autogen/core";

const agent = new AssistantAgent({
  name: "support-agent",
  modelClient,
  tools: [
    {
      name: "lookupPolicy",
      description: "Look up a policy by id",
      parameters: {
        type: "object",
        properties: {
          policyId: { type: "string" },
        },
        required: ["policyId"],
      },
      // Wrong: handler does not match structured args
      execute: async (policyId: string) => {
        const policy = await db.policies.findById(policyId);
        return policy; // might be a DB model instance
      },
    },
  ],
});

// FIXED
import { AssistantAgent } from "@autogen/core";

const agent = new AssistantAgent({
  name: "support-agent",
  modelClient,
  tools: [
    {
      name: "lookupPolicy",
      description: "Look up a policy by id",
      parameters: {
        type: "object",
        properties: {
          policyId: { type: "string" },
        },
        required: ["policyId"],
        additionalProperties: false,
      },
      // Correct: one object argument that matches schema
      execute: async ({ policyId }: { policyId: string }) => {
        const policy = await db.policies.findById(policyId);

        if (!policy) {
          return { found: false };
        }

        return {
          found: true,
          policyId: policy.id,
          status: policy.status,
          premiumCents: policy.premiumCents,
        };
      },
    },
  ],
});

The important part is that AutoGen can only reliably pass structured arguments if your TypeScript handler accepts the same structure. Also keep the result plain and serializable.

Other Possible Causes

1. Model does not support tool calling

Some models can chat fine but fail when asked to emit tool calls. In production this often happens after swapping providers or model IDs.

const modelClient = new OpenAIChatCompletionClient({
  model: "gpt-3.5-turbo", // bad choice for some tool-calling setups
});

Use a model that explicitly supports function/tool calling in your AutoGen version and provider configuration.

const modelClient = new OpenAIChatCompletionClient({
  model: "gpt-4o-mini",
});

2. Tool schema is too loose or invalid

If your schema allows ambiguous input, the model may emit arguments that fail validation.

// weak schema
parameters: {
  type: "object",
  properties: {
    query: { type: "string" },
  },
}

Tighten it:

parameters: {
  type: "object",
  properties: {
    queryType: { type: "string", enum: ["policy", "claim"] },
    queryValue: { type: "string" },
  },
  required: ["queryType", "queryValue"],
  additionalProperties: false,
}

3. Tool returns unsupported values

Returning Date, Map, ORM entities, circular objects, or streams can break serialization.

execute: async () => {
  return {
    createdAt: new Date(), // risky
    record, // ORM entity may contain methods/cycles
  };
};

Fix by normalizing output:

execute: async () => {
  return {
    createdAtIsoString() : new Date().toISOString(),
    recordId,
    status,
  };
};

4. Runtime timeout or network failure inside the tool

Sometimes the “tool calling failure” is just your DB/API timing out.

executeTimeoutMs = 3000;

If the upstream system takes longer than that, AutoGen reports a failed tool call. Increase the timeout or make the tool faster with caching and retries.

How to Debug It

1. •

   Log the exact tool payload

   • •Print the arguments before execution.
   • •Confirm they match your schema exactly.
   • •Look for missing required fields or wrong types.
2. •

   Wrap every tool in a try/catch

   • •Return structured errors instead of throwing raw exceptions.
   • •Log stack traces separately from user-facing output.

execute: async (args) => {
  try {
    return await lookupPolicy(args.policyId);
  } catch (err) {
    console.error("lookupPolicy failed", err);
    return { errorTypeName }; // keep response serializable
 }
}

3. •

   Check provider/model compatibility

   • •Verify the selected model supports tool calling.
   • •If you recently changed models, test with a known-good one first.
4. •

   Validate schema against real requests

   • •Copy the failing arguments from logs.
   • •Run them through your validator locally.
   • •If validation fails, fix schema or prompt instructions.

Prevention

• •

  Define tools with one source of truth:

  • •Keep schema and TypeScript types together.
  • •Use zod or similar validation before execution.
• •

  Return only JSON-safe values:

  • •Strings, numbers, booleans, arrays, and plain objects.
  • •Convert dates to ISO strings.
• •

  Add integration tests for each tool:

  • •Mock one successful call.
  • •Mock one malformed payload.

If you’re seeing tool calling failure in production specifically in AutoGen TypeScript, start with the handler signature and return shape first. That’s where most real failures live.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.