VOX: Voice Agent Builder — Instructions

A Voice For Every Business

Assumptions:

• Core tools (e.g., time checks, website scraping) are auto-provided by the platform.
• Use the JSON Editor tool to create/edit tool descriptors and prompts.
• Use the MongoDB Updater tool to store configurations in your tenant's database.
• Test directly by starting the agent or using provided test scripts.

1. Open the JSON Editor: Use the JSON Editor tool to create a new descriptor file (e.g., my-tools.json).

2. Define the Schema: Each tool follows this structure (based on Zod schema for validation):

{
  "kind": "http_tool",
  "name": "your_tool_name",
  "description": "Brief tool purpose",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": { "type": "string" }
    },
    "required": ["param1"]
  },
  "http": {
    "method": "GET|POST|PUT|PATCH|DELETE",
    "urlTemplate": "https://your-api.com/endpoint/{{param1}}",
    "headers": { "authorization": "Bearer {{secrets.api_key}}" },
    "jsonBodyTemplate": { "key": "{{param1}}" },
    "okField": "ok",
    "timeoutMs": 8000,
    "pruneEmpty": true
  },
  "ui": {
    "onSuccess": {
      "open": {
        "component_name": "catalog_results",
        "title": "Results",
        "props": { "items": "{{response.items}}" }
      }
    },
    "onError": { /* Similar structure */ }
  },
  "enabled": true,
  "priority": 5,
  "version": 1
}

3. Examples:
   • Booking a Room (from Cypress Resort):

     {
       "name": "booking_reserve",
       "description": "Create a reservation for a unit between dates.",
       "parameters": {
         "type": "object",
         "required": ["tenant_id", "unit_id", "check_in", "check_out", "guest"],
         "properties": {
           "tenant_id": { "type": "string" },
           "unit_id": { "type": "string" },
           "check_in": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
           "check_out": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
           "guest": { /* Object with name, email, etc. */ }
         }
       },
       "http": {
         "method": "POST",
         "urlTemplate": "https://your-booking-api.com/api/booking/{{tenant_id}}/reserve",
         "jsonBodyTemplate": { /* Map params to body */ }
       }
     }
     

   • Searching Products (Generalized for e-commerce):

     {
       "name": "search_products",
       "description": "Search inventory for products matching a query.",
       "parameters": {
         "type": "object",
         "required": ["query"],
         "properties": {
           "query": { "type": "string" },
           "limit": { "type": "number", "default": 10 }
         }
       },
       "http": {
         "method": "GET",
         "urlTemplate": "https://your-store-api.com/products?q={{query}}&limit={{limit}}"
       },
       "ui": {
         "onSuccess": {
           "open": {
             "component_name": "catalog_results",
             "props": { "items": "{{response.products}}" }
           }
         }
       }
     }
     

   • MongoDB Query (for custom data fetches):

     {
       "name": "list_things_via_gateway",
       "description": "Browse catalog items (e.g., products, events).",
       "parameters": {
         "type": "object",
         "required": ["tenant_id"],
         "properties": {
           "tenant_id": { "type": "string" },
           "type": { "type": "string" },
           "q": { "type": "string" }
         }
       },
       "http": {
         "method": "POST",
         "urlTemplate": "/api/mongo/gateway",
         "jsonBodyTemplate": { "op": "find", "filter": { /* Mongo query */ } }
       }
     }
     

Validation of Data Against SchemaI validated the provided tool descriptors (the actions array) against the Zod schema (HttpToolDescriptorSchema). All 6 tools parse successfully without errors, meaning they are structurally consistent and compatible with the schema. Here's a summary:Key Compatibilities:All tools have required fields like kind: "http_tool", name, http.method, http.urlTemplate. parameters match the permissive JSON Schema-ish structure (object with type, required, properties, etc.). http configs are valid (methods are correct enums, timeouts are positive integers ≤120000, etc.). ui sections (where present) match HttpUISchema: component_name is string, size is valid enum, props are JSON-like. Optional fields like description, priority, version, enabled are handled correctly. Nested structures (e.g., guest and payment in booking_reserve) validate per their schemas (types, patterns, enums, min/max).

Minor Notes (Not Errors):Some tools use pattern in parameters (e.g., date regex), which is allowed as the schema is permissive. jsonBodyTemplate can be complex objects with templates, which parses fine as JsonValue. No invalid enums or types found. The schema defaults kind to "http_tool" and enabled to true, which aligns with the data.

If you add new tools in the future, this schema will enforce consistency. The data represents a solid "standard" for well-formed descriptors.

4. Save and Upload: Use the MongoDB Updater tool to store the descriptors under your tenantId (e.g., collection: "tools").

Tip: Tools auto-populate the agent's decision-making. Ensure your APIs return structured JSON (e.g., { ok: true, data: {...} }) for easy handling.

1. Build/Examine APIs: Ensure endpoints match your tool descriptors. Use secure auth (e.g., Bearer tokens via secrets).

2. Data Object Structure: Responses should be detailed but concise. Example for a hotel room (adapt for products/recipes/events):

   {
     "name": "Ridge Villa",
     "unitNumber": "1",
     "type": "villa",
     "description": "Magnificent stream view with hot tub and sauna.",
     "rate": 685,
     "currency": "USD",
     "config": {
       "squareFeet": 825,
       "beds": [{ "size": "king", "count": 1 }],
       "amenities": { "wellness": ["hot tub", "sauna"] }
     },
     "images": [
       { "url": "https://example.com/image.jpg", "role": "gallery" }
     ],
     "policies": { "checkInTime": "15:00", "cancellation": { /* details */ } }
   }
   

   • For a product catalog: Include price, stock, images, reviews.
   • For recipes: Ingredients, steps, variations.

3. Test API Calls: Use the JSON Editor to mock requests, or start the agent and query it to trigger tools.

Tip: If data is in MongoDB, use gateway tools for direct queries. For web scraping, leverage core scrapeWebsite.

1. Open the Prompt Editor: Use the JSON Editor tool to create agent-prompt.json.

2. Structure:

   {
     "agent": {
       "tenantId": "your-business-id",
       "name": "Your Agent Name",
       "tone": "warm, concise, professional",
       "style_rules": [ /* Array of rules, e.g., "Always confirm details." */ ]
     },
     "capabilities": {
       "tools": {
         "your_custom_tool": {
           "when": [ /* Triggers, e.g., "User asks for availability." */ ],
           "args": [ /* Required params */ ],
           "success_say": "How to summarize results.",
           "handle_errors": { /* Error codes and responses */ }
         },
         // Include core tools as needed
         "scrapeWebsite": { /* ... */ }
       }
     },
     "policy": { /* Data rules, e.g., "Always check availability first." */ },
     "dialog_flow": { /* High-level steps */ },
     "schema_violation": [ /* Retry rules */ ],
     "response_templates": { /* Pre-formatted responses */ },
     "examples": [ /* User-agent interaction samples */ ]
   }
   

3. Example (Adapted from Cypress for a product sales agent):

   {
     "agent": {
       "name": "Product Guru",
       "tone": "helpful, enthusiastic",
       "style_rules": ["Never invent stock levels—call tools."]
     },
     "capabilities": {
       "tools": {
         "search_products": {
           "when": ["User asks about products or searches."],
           "args": ["query"],
           "success_say": "List top matches with prices and descriptions."
         },
         "show_component": {
           "when": ["Display product images."],
           "args": ["component_name", "media"]
         }
       }
     },
     "dialog_flow": {
       "high_level": ["Search products, show visuals, guide to purchase."]
     }
   }
   

4. Save and Activate: Use MongoDB Updater to store under tenantId. Restart the agent to apply.

Tip: Use examples to train flows, e.g., for a chef agent: Banter on ingredients by calling a recipe search tool.

Test steps

1. Start the Agent: Launch via the platform dashboard or command line.
2. Run Tests:
   • Voice queries: “Book a room for Jan 15–18” (or your use case).
   • Check logs for tool calls and responses.
   • Use test scripts if available, or simulate via direct interaction.
3. Debug:
   • If tools fail: Check schemas and APIs.
   • Refine prompt for better flow.
   • Expand visuals registry as needed (platform will update based on demand).

Tip: Assume good intent; the agent handles edgy queries factually. Expand core tools/visuals via feedback.

Data Model (abridged)

Tool Descriptor Model

Overview of the fields commonly used when defining a tool descriptor.

• name: Unique identifier
• parameters: JSON Schema for args
• http: Config for API call
• ui: Auto-render visuals on outcomes

Prompt Model

The structure that sets personality, constraints, and how tools should be chosen.

• agent: Personality and rules
• capabilities.tools: Per-tool guidelines
• dialog_flow: Conversation structure

Data Object Model

The flexible JSON returned by your APIs that the agent uses for grounding.

• Flexible JSON from your APIs (e.g., products with name, price, images)
• Used for grounding responses