Skip to main content

Documentation Index

Fetch the complete documentation index at: https://watermelon.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Defining Attributes in Swagger

Each parameter defined in your OpenAPI / Swagger schema becomes an attribute that the Agent can fill. These attributes can be defined in:
  • Query parameters
  • Path parameters
  • Request body fields
Example mapping:
API ParameterAttribute (used by the Agent)RequiredType
order_numberorder_numberrequiredstring
postal_codepostal_coderequiredstring
emailemailrequiredstring
The Agent reads these parameters from the schema and collects them from the user when needed.

​
Example Swagger Definition

Below is an example OpenAPI specification defining attributes for an order lookup Action. 
paths:
  /orders:
    get:
      summary: Retrieve order information
      description: Use this action when a user wants to check the status of their order.
      parameters:
        - name: order_number
          in: query
          required: true
          schema:
            type: string
          description: |
            The unique order number assigned when the order was placed.
            Ask the user for their order number if they want to check their order status.

        - name: email
          in: query
          required: true
          schema:
            type: string
          description: |
            The email address used when placing the order.
            Ask the user for this if it has not already been provided.
In this example:
  • order_number and email automatically become attributes
  • the Agent will request these values if they are missing
  • once both values are available, the API call can be prepared.

​
How the AI Uses Parameter Descriptions

The description fields in the Swagger schema are passed to the language model and used as instructions. They help the Agent understand:
  • when the Action should be used
  • what the parameter represents
  • how to ask the user for the value
  • what format the value should have

​
Poor Description

order_number: string
This provides almost no guidance for the Agent.

​
Good Description

description: |
  The unique order number assigned when a customer places an order.
  Ask the user for this number if they want to check their order status.
This gives the Agent enough context to:
  • recognize the correct user intent
  • ask the correct follow-up question
  • extract the value from the conversation.

​
Required vs Optional Attributes

Swagger also defines whether an attribute is required.

​
Required

If required: true, the Agent must collect the value before the Action can run.

​
Optional

If a parameter is optional, the Agent will include it only if the user provides it. Example API request: 
/orders?order_number=123&email=jane@example.com
If both parameters are required, the Agent waits until both values are known before continuing.

​
Handling Partial Inputs

The Agent automatically keeps track of which attributes are already known. Behavior:
  • If some required attributes are missing, the Agent asks only for those fields
  • Users can provide information in any order
  • The Agent maps each answer to the correct parameter
Example conversation flow: User:
I want to check my order.
Agent:
Sure, could you provide your order number?
User:
It’s 12345.
Agent:
Thanks. Can I also get the email address used for the order?
Once all required attributes are available, the Agent prepares the API request.

​
Confirmation Before Execution

Even when all attributes are collected, the Agent will not immediately execute the Action. Instead, the Agent asks the user to confirm the collected values. Example:
I found the following details: Order number: 12345 Email: jane@example.com Is this correct?
The user can then:
  • confirm the values
  • correct any incorrect information
Example correction:
That is not my email address. It should be example@test.com.
After confirmation, the Action is executed.
The wording of confirmation messages can be influenced through Domain Knowledge.
The confirmation step is mandatory and cannot be disabled.

​
Best Practices

To make Actions work reliably with AI Agents:
  • Define all attributes directly in the Swagger schema
  • Use clear parameter names
  • Write descriptive parameter descriptions
  • Indicate clearly whether parameters are required
  • Include guidance in descriptions about how the Agent should ask the user
Well-structured API schemas allow the Agent to collect information naturally and execute Actions reliably.