Agents FAQ

Written By Stanislas

Last updated 18 days ago

Get answers to common questions about building, configuring, testing, and troubleshooting AI agents in Swiftask. This FAQ addresses the most frequently asked questions about agent behavior, knowledge base usage, inconsistent responses, and best practices.

Overview

This FAQ covers common issues and questions about agents, including how to improve agent performance, why agents produce inconsistent results, how to ensure agents use knowledge sources correctly, and how to troubleshoot common problems. Whether you're building your first agent or refining an existing one, you'll find practical answers here.

Frequently Asked Questions

Why is my agent producing inconsistent responses?

Problem: You ask your agent the same question multiple times and get different answers each time.

Causes:

  • Your system prompt is ambiguous or lacks clear instructions

  • You haven't defined specific rules about format and style

  • The agent is using multiple AI models with different behaviors

  • Your knowledge base documents contain conflicting information

Solution:

  1. Go to Objectives & Instructions in your agent configuration

  2. Make your role definition more specific. Instead of "You are a helpful assistant," say "You are an HR documentation specialist focused on creating job descriptions and screening reports"

  3. Add detailed Rules section that defines exact output formats and behavioral guidelines

  4. Test multiple scenarios to verify consistency

  5. If inconsistency persists, simplify your prompt and add more explicit constraints

Example: Instead of "Be professional," write "Always use formal language. Avoid contractions. Structure all documents with clear sections: Title, Overview, Details."

My agent isn't using the knowledge base sources I connected—why?

Problem: You've added documents to your agent's knowledge base, but the agent doesn't reference them or provides generic answers instead.

Causes:

  • Documents aren't indexed or fully processed yet

  • Document names are unclear or non-descriptive

  • Documents are too large or poorly organized

  • The agent's instructions don't explicitly mention using the knowledge base

  • Your questions don't match the content in your documents

Solution:

  1. Verify documents are indexed: In the Knowledge base section, check that all documents show "Indexed and ready" status

  2. Use clear, descriptive names: Rename documents from "Document 1" to "HR Hiring Standards 2025" or "Product Manual v3.2"

  3. Organize into focused documents: Instead of one massive document, create multiple smaller, focused documents. Separate "Recruitment Guidelines" from "Interview Process" from "Salary Ranges"

  4. Add explicit instructions: In your system prompt, add: "When answering questions, always search the connected knowledge base and cite relevant documents"

  5. Test with specific questions: Ask questions that directly relate to your documents' content

  6. Remove unused sources: Delete irrelevant documents—too many sources can slow down search and reduce accuracy

Pro tip: After adding sources, always test your agent by asking questions that should reference the new content. Verify that the agent cites the correct information.

How do I make my agent more accurate and reliable?

Problem: Your agent sometimes makes up information, provides inaccurate answers, or doesn't follow its instructions.

Solution:

Step 1: Refine your instructions

  • Be as specific as possible about what the agent does and how it should behave

  • Break tasks into numbered steps to create a logical workflow

  • Add clear rules about tone, format, and accuracy

  • Example: Instead of "Generate documents," write: "1. Analyze the request to determine document type. 2. Draft content with clear sections. 3. Use export_to_pdf tool to generate the final document"

Step 2: Test comprehensively

  • Don't wait until your agent is fully configured—test after each major change

  • Use realistic test cases, not just simple queries

  • Test edge cases—ask questions outside your agent's scope to verify it handles them gracefully

  • Ask the same question multiple times to check consistency

Step 3: Add relevant knowledge sources

  • Start with 2-3 core documents containing the most critical information

  • Test the agent's responses, then add more sources as needed

  • Keep documents focused and organized

  • Update sources regularly if your documentation changes

Step 4: Configure skills properly

  • Make sure each skill has all required parameters configured

  • Add explicit instructions about when and how to use each skill

  • Example: "After drafting the document, use the export_to_pdf tool to create a PDF file for the user"

Step 5: Iterate and refine

  • After testing, identify areas for improvement

  • Return to configuration and make adjustments

  • Test again with the same questions to verify improvements

  • Repeat this cycle until your agent performs reliably

Why is my agent using tools incorrectly?

Problem: Your agent isn't using skills/tools as expected, or uses them at the wrong time.

Causes:

  • Tasks don't explicitly mention when and how to use tools

  • Tool parameters aren't configured correctly

  • The agent doesn't understand the sequence of operations

Solution:

  1. Edit your system prompt and make tasks explicitly mention tool usage

  2. Add the exact sequence: "After [step 1], use [tool name] to [action]"

  3. In the Skills section, verify all required parameters are configured

  4. Test each skill individually to ensure it works correctly

  5. Add examples in your instructions: "Example: After creating the job description, use export_to_pdf tool to generate a downloadable PDF"

Example prompt:

Tasks: 1. Analyze the request to determine document type 2. Draft the content with clear sections 3. Use the export_to_pdf tool to generate the final document 4. Provide the download link to the user

Why does my agent sometimes use the fallback LLM instead of my primary model?

Problem: Your agent switches to a fallback AI model unexpectedly.

Causes:

  • Your primary model is unavailable or overloaded

  • Your workspace has insufficient credits

  • Your plan limits access to certain models

Solution:

  1. Check your workspace credit balance in the admin dashboard

  2. Consider upgrading your plan if you hit credit limits frequently

  3. Monitor your agent's usage to understand consumption patterns

  4. If specific models are unavailable, contact Swiftask support

How do I test my agent effectively?

Problem: You're not sure how to test your agent properly or what to look for.

Solution:

Use the test panel:

  1. In agent configuration, find the test panel on the right side

  2. Click the Discuss button on your agent card

  3. A chat window opens—start testing immediately

Evaluate these key areas:

  • Does it follow instructions? Check that the agent behaves according to your system prompt. If it deviates, refine your instructions to be more specific

  • Does it use knowledge base correctly? Ask questions that require information from your connected documents. Verify it references the right sources

  • Do skills work? Test each skill you added. For example, verify that PDF export works and documents are formatted correctly

  • Are responses consistent? Ask the same question multiple times or rephrase it. The agent should provide consistent answers

  • Is tone and format appropriate? Check that language, professionalism, and output format match your requirements

Best practices:

  • Test early and often—don't wait until your agent is fully configured

  • Use realistic test cases that match actual user questions

  • Test edge cases—ask questions outside your agent's scope

  • Document what works so you understand your agent's strengths

  • Keep testing notes to track improvements over time

Can I use the same knowledge base with multiple agents?

Yes. You can connect the same documents to multiple agents. This is useful for:

  • Creating department-specific agents that all access company policies

  • Building specialized agents that share a common knowledge base

  • Ensuring consistency across your team's agents

Tip: Use descriptive document names so you can easily identify which sources are used by which agents.

How do I fix my agent's knowledge base if documents aren't being found?

Problem: Your agent can't find information even though it's in your knowledge base.

Solution:

  1. Check document status: Verify documents are fully indexed (shows "Indexed and ready")

  2. Use clear structure: Organize content with headings, bullet points, and numbered lists—structured content is easier for agents to parse

  3. Keep documents focused: Instead of one massive document, use multiple smaller, focused documents

  4. Verify document names: Use descriptive names like "Product FAQ 2025" instead of "Document 1"

  5. Update regularly: If documentation changes, update or replace the knowledge base sources immediately

  6. Remove irrelevant sources: Delete sources no longer relevant—too many sources can reduce search accuracy

  7. Test after changes: Always test your agent after adding or updating sources

What's the difference between creating an agent from scratch vs. from a template?

From Template:

  • Faster setup—pre-configured objectives, instructions, and sometimes skills

  • Good starting point for common use cases (customer support, document analysis, etc.)

  • You still need to customize the system prompt and add your knowledge base

  • Ideal for users new to agent building

From Scratch:

  • Full control over every aspect of your agent

  • More flexibility for highly customized workflows

  • Requires more configuration but gives you exactly what you need

  • Best when templates don't match your specific use case

Recommendation: If you're new to agents, start with a template and customize it. If you need something very specific, build from scratch.

How do I share my agent with my team?

Solution:

  1. Open your agent

  2. Click the agent actions menu (three dots)

  3. Select Share the agent

  4. Choose sharing options:

    • Share with specific team members

    • Share with groups

    • Make it public (for external users)

  5. Team members will see your agent in their "Shared with me" section

Tip: Always test your agent thoroughly before sharing. Verify welcome messages, starter questions, and agent responses work as expected.

What are starter questions and why should I use them?

What they are: Pre-written example questions shown to users when they first interact with your agent.

Why use them:

  • Show users what your agent can do

  • Reduce friction—users don't have to think of questions

  • Guide conversations toward your agent's strengths

  • Improve user experience

How to set them:

  1. In agent configuration, go to Appearance settings

  2. Add 3-4 common questions that represent your agent's main use cases

  3. Make them specific and action-oriented

  4. Example: "Generate a job description for a Marketing Manager" instead of "What can you do?"

How do I monitor my agent's usage and costs?

Solution:

  1. Go to Workspace Administration → Dashboard

  2. Check agent consumption metrics

  3. Monitor credit usage by agent

  4. Review usage patterns to optimize costs

Best practices:

  • Check usage regularly (weekly recommended)

  • Disable unnecessary agent skills—each active skill can consume additional credits

  • Use knowledge base instead of repeated attachments

  • Start new conversations when they become too long (reduces credit consumption per message)

Why should I test my agent after adding knowledge sources?

Importance:

  • Verifies that documents were indexed correctly

  • Confirms the agent can find and reference your content

  • Ensures answers are accurate and properly cited

  • Identifies any gaps in your knowledge base

How to test:

  1. Ask questions that should reference the new content

  2. Verify the agent cites correct sources

  3. Check that answers are accurate

  4. Look for any missing information

What should I do if my agent is giving me errors?

Common issues:

"Sources not found"

  • Check that documents are indexed and accessible

  • Verify document names are clear and descriptive

  • Ensure you've connected sources to the agent

"Skill not working"

  • Verify skill parameters are configured correctly

  • Check that your instructions explicitly mention when to use the skill

  • Test the skill individually

"Agent not responding"

  • Check your workspace credit balance

  • Verify the agent's configuration is complete

  • Try testing in the test panel

"Inconsistent responses"

  • Refine your system prompt to be more specific

  • Add clearer rules about format and output

  • Test multiple scenarios

Tips & Best Practices

Start simple: Build a basic agent with clear instructions and a few documents. Test thoroughly. Then add complexity.

Be specific: The more specific your role definition and instructions, the better your agent performs. Avoid generic descriptions.

Structure content: Organize knowledge base documents with headings, bullet points, and numbered lists. Structured content is easier for agents to parse.

Test early and often: Don't wait until your agent is fully configured. Test after each major change.

Use realistic test cases: Test with actual questions your users will ask, not just simple queries.

Document what works: Keep notes on successful test cases and effective prompts. This helps you understand what your agent does well.

Update regularly: Keep your knowledge base current. Outdated information leads to incorrect agent responses.

Monitor usage: Check your agent's usage metrics regularly to understand how external users interact with it. Adjust based on real usage patterns.

Additional Resources

  • Introduction to Agents – Learn what agents are and how they work

  • Create AI agent step by step – Build your first custom agent

  • Setting objectives & instructions – Define your agent's role and behavior

  • Sources (knowledge base) – Connect documents to your agent

  • Skills (AI tools) – Add capabilities like file export and email

  • Testing & interaction – Test and refine your agent

  • Share an agent – Give teammates access to your agent

Ready to improve your agents? Start by reviewing your agent's instructions and testing them with realistic questions. Refine based on results, and your agent will improve with each iteration.