Agent Troubleshooting

Common reasons an agent — especially a web chat agent — fails to work, and how to fix them. Each section lists the symptom, the cause, and the fix.

tip

Most "my agent won't respond" cases come down to one of two mismatches: a capability without its catalog, or a deployment URL that doesn't match where the widget is embedded. Both are covered below.

---

Capabilities without a matching catalog

Symptom: The chat agent loads but fails to work — it can't complete requests, or the conversation doesn't behave as expected — even though the configuration looks correct.

Cause: Every capability you enable (BusinessSupportServices) is backed by a catalog the agent reads from and acts on. If you enable a capability but haven't set up its corresponding catalog, the agent has nothing to operate against, and the agent won't work.

Capabilities are set as capabilities on the dynamic agent (or as supportedServices on the instruction configuration in the traditional setup). Each maps to a catalog you must have configured:

Capability (BusinessSupportServices)	Requires catalog
APPOINTMENT_MANAGEMENT	Services
RESERVATION_MANAGEMENT	Reservations
MENU_ORDER_MANAGEMENT	Menu
PRODUCT_ORDER_MANAGEMENT	Products
PROPERTY_MANAGEMENT	Property
INVENTORY_MANAGEMENT	Product stock (part of Products)
NONE	None — information-only (see below)

Fix: For every capability the agent declares, either:

1. Set up the corresponding catalog so the agent has data to act on, or
2. Remove the capability if you don't need that action.

Don't enable a capability "just in case" — an enabled capability with no catalog behind it breaks the agent.

---

Information-only agents: use BusinessSupportServices.NONE

Symptom: You only want the agent to answer questions (no bookings, orders, or reservations), but it won't work because capabilities are enabled without catalogs.

Cause: Any real capability implies a catalog. A pure Q&A agent shouldn't declare one.

Fix: Set capabilities to BusinessSupportServices.NONE. This runs the agent as a pure information assistant with no catalog requirement. Pair it with knowledge sources so it has material to answer from.

TypeScript

import { WiilClient } from 'wiil-js';
import { BusinessSupportServices } from 'wiil-core-js';

const client = new WiilClient({ apiKey: process.env.WIIL_API_KEY! });

const result = await client.dynamicWebAgent.create({
  assistantName: 'Info',
  websiteUrl: 'https://example.com',
  capabilities: [BusinessSupportServices.NONE], // pure information / Q&A
  knowledgeSourceIds: ['knowledge_help_center'],
});

Python

import os
from wiil import WiilClient
from wiil.models.service_mgt import BusinessSupportServices

client = WiilClient(api_key=os.environ['WIIL_API_KEY'])

result = client.dynamic_web_agent.create(
    assistant_name='Info',
    website_url='https://example.com',
    capabilities=[BusinessSupportServices.NONE],  # pure information / Q&A
    knowledge_source_ids=['knowledge_help_center'],
)

note

NONE must be the agent's only capability — don't combine it with other services. Give the agent knowledge sources so it has content to ground its answers.

---

Web deployment URL does not match the configured channel

Symptom: The widget appears on your page, but the chat agent won't start or respond.

Cause: A web deployment channel is configured with a specific website URL. The widget must be embedded on a page whose URL matches that configured URL. If the page where the widget runs doesn't match the deployment's configured URL, the agent won't work.

Fix: Make the deployment channel's configured website URL match the site where the widget is embedded (or update the embed location to match the configuration). Check that both line up exactly, including:

• Protocol — http vs https
• Host / subdomain — example.com vs www.example.com vs app.example.com
• Domain — production vs staging/preview domains
• Path and trailing slash, if the configuration is path-specific

If you serve the widget from more than one domain (for example, staging and production), configure a separate deployment per domain rather than reusing one.

See Web Channels for creating the channel and deployment, and the Widget Configuration Guide for the embed snippet (note that data-config-id must be the deployment's ID).

---

Quick checklist

Before reporting a broken agent, confirm:

• Every enabled capability has its corresponding catalog set up — or capabilities are set to BusinessSupportServices.NONE.
• The deployment channel's website URL matches where the widget is embedded (protocol, host, and domain).
• The widget's data-config-id is the correct deployment ID.
• For information-only agents, knowledge sources are attached so the agent has content to answer from.

---

Related

• Dynamic Agent Setup Guide — deploying phone and web agents, capabilities, and knowledge
• Web Channels — creating web channels and deployments
• Widget Configuration Guide — embedding and configuring the chat widget
• Channel Troubleshooting — channel- and widget-level issues