Runtime Type Validation with Pydantic and Zod · Flow Cadax | Flow Cadax

Beginner/Zero-Error JSON Schema Tool Calling & Function Signatures

High PriorityBeginner 35 min read & practiceFree Preview Sample

Not Started

Short lesson

Runtime Type Validation with Pydantic and Zod

Function calling (tool calling) is the bridge between human language and computer code. Instead of generating conversational English, the LLM emits a strictly formatted JSON object matching an exact schema—turning fuzzy user desires into clean API arguments that n8n can execute with 100% precision.

Conversational Output (Useless to APIs)

User: 'Book a room for Alice on Friday'. Model replies: 'Sure, I would be happy to help book a hotel room for Alice on October 18th for 2 nights!' -> Downstream API cannot use this raw text.

Structured Function Call (Machine-Executable)

Model outputs pure JSON: { 'name': 'book_reservation', 'arguments': { 'guest_name': 'Alice', 'check_in': '2026-10-18', 'nights': 2 } } -> Directly sent to Hotel Booking API.

Go deeperRuntime Type Validation with Pydantic and Zod: Enterprise Masterclass

5 Parts

Chapters:5 Parts Available

PART 01Foundational Context

1 of 5

How Function Calling Actually Works Under the Hood

Many people think LLMs execute code directly. They don't. When you give an n8n AI Agent a tool, n8n sends the tool's JSON Schema to OpenAI or Anthropic alongside the user prompt. The model recognizes that a tool is available, stops outputting standard conversational words, and instead emits a specialized structured JSON payload containing the function name and exact arguments. n8n catches this payload, runs the actual HTTP request or database query, and sends the raw result back to the model.

Architectural Principle

Pydantic (Python) and Zod (TypeScript) allow defining data models as native code classes, automatically generating JSON Schemas and validating inputs.

Enterprise Significance

Guarantees that tool arguments are type-safe (e.g. emails are valid, dates are parsed, numbers are positive) before executing backend code.

Operational Requirement

Use Pydantic field validators (@field_validator) to enforce domain business logic on tool inputs.

PART 02Technical Breakdown

2 of 5

Visual Architecture: The Function Calling Payload Handshake

The precise JSON request/response handshake between n8n and the LLM:

n8n Canvas Workflow & Agent Execution Visualizer

Agent Flowchart

┌─────────────────────────────────────────────────────────────────┐
│              Function Calling Protocol Handshake                │
│                                                                 │
│  [Step 1: n8n sends User Query + Available Tool Schemas]        │
│  Payload to OpenAI/Claude:                                      │
│  { "messages": [{ "role": "user", "content": "Refund order 99" }],│
│    "tools": [{                                                  │
│      "type": "function",                                        │
│      "function": {                                              │
│        "name": "stripe_refund",                                 │
│        "parameters": {                                          │
│          "type": "object",                                      │
│          "properties": {                                        │
│            "order_id": { "type": "string" },                    │
│            "reason": { "type": "string", "enum": ["fraud", "return"] }│
│          },                                                     │
│          "required": ["order_id", "reason"]                     │
│        }                                                        │
│      }                                                          │
│    }]                                                           │
│  }                                                              │
│                              │                                  │
│                              ▼                                  │
│  [Step 2: LLM Emits Tool Call Signal]                           │
│  Model output:                                                  │
│  { "tool_calls": [{                                             │
│      "name": "stripe_refund",                                   │
│      "arguments": "{\"order_id\": \"99\", \"reason\": \"return\"}"    │
│  }] }                                                           │
│                              │                                  │
│                              ▼                                  │
│  [Step 3: n8n Executes Native HTTP Tool & Feeds Result Back]    │
│  POST https://api.stripe.com/v1/refunds -> Returns 200 OK       │
└─────────────────────────────────────────────────────────────────┘

Swipe horizontally for full architecture⟷

PART 03Technical Breakdown

3 of 5

Enterprise Case Study: Multilingual Airline Rebooking Assistant

An international airline operated customer support in 14 languages. Passengers frequently typed messages like: 'Mi vuelo de Madrid a Londres fue cancelado, quiero el siguiente avión' (Spanish: My flight from Madrid to London was canceled, I want the next plane).

The Implementation

Connected an n8n AI Agent with a structured flight rebooking tool schema requiring: `origin_airport: string (3-letter IATA)`, `destination_airport: string (3-letter IATA)`, and `preferred_time: ISO timestamp`.

Zero-Shot Normalization

Even though the customer typed in informal Spanish, the LLM extracted and normalized the exact parameters: `{ origin_airport: 'MAD', destination_airport: 'LHR', rebook_priority: 'NEXT_AVAILABLE' }`.

Results

Handled 28,000 ticket rebookings during a severe weather storm across Europe with zero human agent escalation and zero booking schema errors.

PART 04Technical Breakdown

4 of 5

Schema Types & Constraints Reference

How to define bulletproof parameters that prevent LLM hallucination:

JSON Schema Keyword	Example Usage	Why It Prevents Bugs
enum	['STANDARD', 'EXPRESS', 'OVERNIGHT']	Forces the model to select ONLY from an approved list; prevents invalid strings
pattern (regex)	'^CUST-[0-9]{6}$'	Enforces strict string formats like Customer IDs or tracking numbers
minimum / maximum	minimum: 1, maximum: 100	Guarantees numeric inputs don't pass negative numbers or overflow values
description	'Order ID found on top-right of receipt'	Provides context to help the model find the right field in messy inputs
required	['email', 'amount']	Ensures the LLM never executes the tool with missing mandatory arguments

Scroll table sideways→

PART 05Key Takeaways

5 of 5

Senior Architect Function-Calling Guidelines

Best practices for writing production-grade tool schemas in n8n:

Use Strict Mode (`strict

true`): When supported by the model (OpenAI & Anthropic), enabling strict schema mode guarantees 100% adherence to your JSON schema definition.

2. Keep the Number of Tools Under 10 per Agent: Giving an agent 30 tools overwhelms its context window, increases latency, and causes tool confusion. If you have 30 tools, use an Intent Router to dispatch to specialized subagents.

Never Put Secrets in Tool Definitions

Tool schemas are sent directly over the wire to external LLM providers. Never hardcode API keys or internal database passwords inside tool descriptions.

Senior AI Agent Architect Field Insight

“A tool schema is a contract between probabilistic AI and deterministic code. Make that contract as strict and narrow as possible, and your automations will never crash.”

Add a personal note (optional)Open

Previous Topic

Strict JSON Schema Construction for LLM Function Interfaces

Up Next in Sequence

Self-Healing Retries on Malformed Tool Arguments