Build AI Agents

Parameters

View as MarkdownOpen in Claude

Parameter Structure

Parameters use JSON Schema format. The schema is identical across all SDK languages — only the host-language syntax for expressing the object differs:

parameters={
    "type": "object",
    "properties": {
        "param_name": {
            "type": "string",           # Data type
            "description": "Description" # Help AI understand the parameter
        }
    },
    "required": ["param_name"]          # Required parameters
}

Parameter Definition Across Languages

LanguageSyntax for Parameters Object
Python{"type": "object", "properties": {"p": {"type": "string", "description": "d"}}, "required": ["p"]}
TypeScript{ type: 'object', properties: { p: { type: 'string', description: 'd' } }, required: ['p'] }

All parameter examples below use Python dict syntax. The JSON Schema structure is the same in every language — translate the dict/map syntax to your language as shown in the table above.

Parameter Types

TypeDescriptionExample Values
stringText values"hello", "12345", "New York"
numberNumeric values42, 3.14, -10
integerWhole numbers only1, 42, -5
booleanTrue/falsetrue, false
arrayList of values["a", "b", "c"]
objectNested structure{"key": "value"}

String Parameters

Basic string parameters:

parameters={
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "Customer name"
        },
        "email": {
            "type": "string",
            "description": "Email address"
        },
        "phone": {
            "type": "string",
            "description": "Phone number in any format"
        }
    },
    "required": ["name"]
}

Enum Parameters

Restrict to specific values:

parameters={
    "type": "object",
    "properties": {
        "department": {
            "type": "string",
            "description": "Department to transfer to",
            "enum": ["sales", "support", "billing", "returns"]
        },
        "priority": {
            "type": "string",
            "description": "Issue priority level",
            "enum": ["low", "medium", "high", "urgent"]
        }
    },
    "required": ["department"]
}

Number Parameters

parameters={
    "type": "object",
    "properties": {
        "quantity": {
            "type": "integer",
            "description": "Number of items to order"
        },
        "amount": {
            "type": "number",
            "description": "Dollar amount"
        },
        "rating": {
            "type": "integer",
            "description": "Rating from 1 to 5",
            "minimum": 1,
            "maximum": 5
        }
    },
    "required": ["quantity"]
}

Boolean Parameters

parameters={
    "type": "object",
    "properties": {
        "gift_wrap": {
            "type": "boolean",
            "description": "Whether to gift wrap the order"
        },
        "express_shipping": {
            "type": "boolean",
            "description": "Use express shipping"
        }
    }
}

Array Parameters

parameters={
    "type": "object",
    "properties": {
        "items": {
            "type": "array",
            "description": "List of menu items to order",
            "items": {
                "type": "string"
            }
        },
        "tags": {
            "type": "array",
            "description": "Tags to apply",
            "items": {
                "type": "string",
                "enum": ["urgent", "vip", "callback"]
            }
        }
    },
    "required": ["items"]
}

Object Parameters

parameters={
    "type": "object",
    "properties": {
        "address": {
            "type": "object",
            "description": "Delivery address",
            "properties": {
                "street": {"type": "string"},
                "city": {"type": "string"},
                "zip": {"type": "string"}
            },
            "required": ["street", "city", "zip"]
        }
    },
    "required": ["address"]
}

Optional vs Required Parameters

parameters={
    "type": "object",
    "properties": {
        # Required - AI must extract this
        "order_number": {
            "type": "string",
            "description": "Order number (required)"
        },
        # Optional - AI will include if mentioned
        "include_tracking": {
            "type": "boolean",
            "description": "Include tracking details"
        },
        # Optional with default handling
        "format": {
            "type": "string",
            "description": "Output format",
            "enum": ["brief", "detailed"],
            "default": "brief"
        }
    },
    "required": ["order_number"]  # Only order_number is required
}

Default Values

Handle missing optional parameters in your handler. The pattern for accessing arguments with defaults varies by language:

LanguageGet with Default
Pythonargs.get("key", "default")
TypeScriptargs.key ?? 'default' or args['key'] ?? 'default'
def search_products(self, args, raw_data):
    # Get required parameter
    query = args.get("query")
    # Get optional parameters with defaults
    category = args.get("category", "all")
    max_results = args.get("max_results", 5)
    sort_by = args.get("sort_by", "relevance")
    # Use parameters
    results = self.db.search(
        query=query,
        category=category,
        limit=max_results,
        sort=sort_by
    )
    return FunctionResult(f"Found {len(results)} products")

Parameter Descriptions

Good descriptions help the AI extract parameters correctly:

parameters={
    "type": "object",
    "properties": {
        # Good - specific format guidance
        "order_number": {
            "type": "string",
            "description": "Order number, usually starts with ORD- followed by digits"
        },
        # Good - examples help
        "date": {
            "type": "string",
            "description": "Date in MM/DD/YYYY format, e.g., 12/25/2024"
        },
        # Good - clarifies ambiguity
        "amount": {
            "type": "number",
            "description": "Dollar amount without currency symbol, e.g., 29.99"
        },
        # Bad - too vague
        "info": {
            "type": "string",
            "description": "Information"  # Don't do this
        }
    }
}

Complex Example

from signalwire import AgentBase, FunctionResult
class TravelAgent(AgentBase):
    def __init__(self):
        super().__init__(name="travel-agent")
        self.add_language("English", "en-US", "rime.spore")
        self.define_tool(
            name="search_flights",
            description="Search for available flights between cities",
            parameters={
                "type": "object",
                "properties": {
                    "from_city": {
                        "type": "string",
                        "description": "Departure city or airport code"
                    },
                    "to_city": {
                        "type": "string",
                        "description": "Destination city or airport code"
                    },
                    "departure_date": {
                        "type": "string",
                        "description": "Departure date in YYYY-MM-DD format"
                    },
                    "return_date": {
                        "type": "string",
                        "description": "Return date in YYYY-MM-DD format (optional for one-way)"
                    },
                    "passengers": {
                        "type": "integer",
                        "description": "Number of passengers",
                        "minimum": 1,
                        "maximum": 9
                    },
                    "cabin_class": {
                        "type": "string",
                        "description": "Preferred cabin class",
                        "enum": ["economy", "premium_economy", "business", "first"]
                    },
                    "preferences": {
                        "type": "object",
                        "description": "Travel preferences",
                        "properties": {
                            "nonstop_only": {
                                "type": "boolean",
                                "description": "Only show nonstop flights"
                            },
                            "flexible_dates": {
                                "type": "boolean",
                                "description": "Search nearby dates for better prices"
                            }
                        }
                    }
                },
                "required": ["from_city", "to_city", "departure_date"]
            },
            handler=self.search_flights
        )
    def search_flights(self, args, raw_data):
        from_city = args.get("from_city")
        to_city = args.get("to_city")
        date = args.get("departure_date")
        passengers = args.get("passengers", 1)
        cabin = args.get("cabin_class", "economy")
        prefs = args.get("preferences", {})
        nonstop = prefs.get("nonstop_only", False)
        # Your flight search logic here
        return FunctionResult(
            f"Found 3 flights from {from_city} to {to_city} on {date}. "
            f"Cheapest: $299 {cabin} class"
        )

Validating Parameters

Add validation in your handler:

def process_payment(self, args, raw_data):
    amount = args.get("amount")
    card_last_four = args.get("card_last_four")
    # Validate amount
    if amount is None or amount <= 0:
        return FunctionResult(
            "Invalid amount. Please specify a positive dollar amount."
        )
    # Validate card
    if not card_last_four or len(card_last_four) != 4:
        return FunctionResult(
            "Please provide the last 4 digits of your card."
        )
    # Process payment
    return FunctionResult(f"Processing ${amount:.2f} on card ending {card_last_four}")

Parameter Best Practices

DO:

  • Use clear, descriptive names (order_number not num)
  • Provide detailed descriptions with examples
  • Use enum for fixed choices
  • Mark truly required parameters as required
  • Handle missing optional parameters with defaults

DON’T:

  • Require parameters the caller might not know
  • Use ambiguous descriptions
  • Expect perfect formatting (be flexible in handlers)
  • Create too many required parameters