Managing Your Agents
Agents are your AI-powered virtual assistants that answer calls, SMS messages, and chats on behalf of your business. This guide shows you how to create, configure, and customize them.
What is an Agent?
Think of an agent as a virtual employee. Each agent has:
| Component | Description |
|---|---|
| Name & Avatar | How the agent identifies itself to customers |
| Behaviors | Instructions and skills that define how the agent acts |
| Knowledge Base | Information the agent uses to answer questions |
| Deployments | Where the agent responds (phone numbers, chat widgets) |
A single agent can handle phone calls, SMS messages, AND website chats. You can also create separate agents for different purposes (sales, support, etc.).
Viewing Your Agents
- Click Agents in the left menu under "AI Configuration"
- You'll see all your agents displayed as cards
- Click any agent card to view and edit its details
Agent Cards
Each card shows:
- Avatar — The agent's profile picture
- Name — The agent's display name
- Description — Your internal notes about the agent
- Warning icon — Appears if no business profile is assigned (the agent may not perform well without one)
Click the Create Agent card (with the + icon) to add a new AI agent.
Agent Settings
When you click on an agent, you'll see the agent detail page with several collapsible sections. The page is organized into three columns:
- Left: Agent name and avatar
- Center: Configuration sections
- Right: Test Chat panel
Basic Information
Agent Name
What the agent calls itself. Customers will hear/see this name during conversations.
Example: "Hi, this is Sarah from Sunshine Plumbing!"
Avatar
A picture representing your agent. You can:
- Upload a custom image (click the upload area)
- Adjust positioning, rotation, and scale using the editor
- Choose something that represents your business brand
Avatar Editor Tips
When uploading an avatar:
- Click the upload area or drag an image onto it
- Use the slider controls to adjust:
- Position: Move the image up/down/left/right
- Scale: Zoom in or out
- Rotation: Rotate the image
- The preview shows exactly how it will appear to customers
Description
Add a brief note to help you (and your team) remember what this agent is for. Customers never see this description.
Examples:
- "Main sales agent for new customer inquiries"
- "Support agent for existing customers with questions"
- "After-hours agent with limited capabilities"
Behaviors
Behaviors define how your agent acts in conversations. Each behavior combines two parts:
Prompts
Textual instructions that tell the agent how to behave:
- Personality and communication style
- How to handle specific questions or scenarios
- What information to prioritize
- When to escalate to a human
Skills
Tools available to the agent to execute actions:
| Skill | Description |
|---|---|
| Appointment Scheduling | Check calendar availability and book appointments |
| Lead Capture | Collect customer information (name, phone, email, custom questions) |
| Call Forwarding | Transfer calls to a human when needed |
| Weather Check | Look up weather information for relevant businesses |
| Custom Integrations | Connect to your business systems |
Managing Behaviors
Adding a behavior:
- Click Add Behavior in the Behaviors section
- Choose from:
- Templates — Pre-built behaviors from Need Theo
- Your Behaviors — Behaviors you've already created
- Create new — Build a custom behavior from scratch
Reordering behaviors:
- Drag and drop behaviors to change their order
- Order may influence how the agent prioritizes instructions
Enabling/disabling behaviors:
- Toggle the switch next to any behavior to enable or disable it
- Disabled behaviors are saved but not active
Configuring behaviors:
- Some behaviors have additional settings
- Click the expand arrow to see configuration options
For best results, assign a Business Profile to your agent in the Knowledge Base section. Without it, the agent won't have essential business information like your hours, services, and contact details.
Knowledge Base
Knowledge your agent can access during conversations. The more relevant knowledge you provide, the better your agent will perform.
Types of knowledge:
- Business Profile — Essential business information (hours, services, location)
- FAQs — Common questions and answers
- Documents — PDFs, text files, and other documents
- Website Content — Information scraped from your website
Managing Knowledge
Adding knowledge:
- Click Add Knowledge in the Knowledge Base section
- Select from available knowledge items
- Or click Create New to add new knowledge to your account
Removing knowledge:
- Click the trash icon next to any knowledge item
- This only removes the association — the knowledge itself remains in your Knowledge Base
For detailed information about creating and managing knowledge, see the Knowledge Base guide.
Web Deployments
Web deployments let you add a chat widget to your website powered by this agent.
Creating a Deployment
- Click New Deployment in the Web Deployments section
- Give it a name (for your reference)
- Configure the welcome message and appearance
- Copy the embed code to add to your website
Deployment Settings
When editing a deployment, you can customize:
| Setting | Description |
|---|---|
| Name | Internal name to identify this deployment |
| Welcome Message | First message displayed when visitors open the chat |
| Default Language | Language the agent uses to start conversations |
| Primary Color | Color of the chat button and user message bubbles |
| Header Color | Background color of the chat window header |
| Font Family | Typography style (Inter, Roboto, Open Sans, etc.) |
A live preview updates in real-time as you make changes.
For detailed installation instructions, see the Chatbot Installation guide.
Phone Deployments
Phone deployments assign phone numbers to your agent for voice and SMS conversations.
Adding a Phone Number
- Click Add Phone in the Phone Deployments section
- Select an available phone number from your account
- Configure the voice settings
Phone Settings
For each phone number, you can configure:
| Setting | Description |
|---|---|
| Voice | How your agent sounds (male/female, different accents) |
| Language | The language the agent speaks |
| Welcome Message | Pre-recorded message before Theo answers (optional) |
| Max Call Duration | Maximum call length in minutes (1-60) |
| SMS Enabled | Toggle SMS support on this number (Canadian numbers only) |
The welcome message is typically used for:
- Legal disclosures ("This call may be recorded...")
- Initial greetings before the AI takes over
- Holiday announcements or special notices
For more details, see the Voice Agents guide.
Post-Conversation Hooks
Webhooks that fire after a conversation ends. Use these to:
- Send conversation data to your CRM
- Trigger automation workflows
- Update external systems
Setting Up Webhooks
- Click Add Hook in the Post-Conversation Hooks section
- Enter the webhook URL
- Configure which events trigger the webhook
- Save your settings
The webhook receives a JSON payload with conversation details.
Advanced Settings
Additional configuration options for power users:
AI Reasoning Capture
When enabled, stores the AI's reasoning process for each response. This is useful for:
- Debugging unexpected agent behavior
- Understanding why the agent made certain decisions
- Training and improving your agent over time
View captured reasoning in the Conversations page.
Test Chat
The Test Chat panel appears on the right side of the agent page. Use it to interact with your agent exactly as customers would.
How to use:
- Type a message in the input field
- Press Enter or click Send
- See how your agent responds
- Click the refresh icon to start a new conversation
Things to test:
- Basic questions about your business
- Appointment booking requests
- Edge cases and unusual requests
- Escalation triggers
Always test your agent thoroughly before deploying to production. Try various scenarios your customers might encounter.
Creating Multiple Agents
Some businesses benefit from multiple agents for different purposes:
| Agent Type | Use Case |
|---|---|
| Sales Agent | New customer inquiries, lead qualification |
| Support Agent | Existing customer questions, troubleshooting |
| After-Hours Agent | Limited capabilities, message-taking only |
| Training Agent | Internal use for staff questions |
To create a new agent:
- Go to Agents
- Click the Create Agent card
- Enter a name and description
- Configure the agent's settings and behaviors
Best Practices
Start Simple
Begin with basic settings and add complexity only when needed. A simple, well-configured agent often outperforms an over-complicated one.
Test Regularly
After making any changes:
- Use the Test Chat to verify behavior
- Make a test call if using voice
- Check that all skills work as expected
Review Real Conversations
Regularly check the Conversations page to:
- Identify incorrect information
- Spot confused or unexpected responses
- Find missed opportunities
- Discover new questions to add to your knowledge base
Keep Knowledge Updated
When your business changes, update your agent's knowledge:
- New services or products
- Price changes
- Updated hours
- Special promotions or seasonal changes
Common Questions
Can I have different agents for phone and chat?
Yes! Create separate agents and assign each to different deployments. This lets you customize the experience for each channel.
How do I change what my agent says?
You have several options:
- Business Profile — Update core business information
- Knowledge Base — Add or modify knowledge items
- Behaviors — Edit the prompts that guide agent behavior
Can the agent speak other languages?
Yes! You can configure the default language for:
- Chat widgets — Set in deployment settings
- Phone calls — Set per phone number
The agent can also detect and adapt to the user's language in many cases.
What if the agent gives wrong information?
- Check your Business Profile — Is the correct information there?
- Check your Knowledge Base — Is there conflicting information?
- Review the Conversation — Use AI Reasoning (if enabled) to understand why
- Contact support if the issue persists
What happens if I delete an agent?
Deleting an agent will:
- Remove the agent permanently
- Delete all associated web deployments (chat widgets stop working)
- Remove phone number assignments (numbers return to available pool)
- Preserve conversation history (visible in Conversations)
Make sure you want to delete before confirming.
Need Help?
- Check our Troubleshooting Guide
- Email support@needtheo.com