> For the complete documentation index, see [llms.txt](https://alludium.gitbook.io/alludium-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alludium.gitbook.io/alludium-docs/15.-best-practices-troubleshooting-and-faqs.md). # Best Practices, Troubleshooting & FAQs This section brings together **platform best practices** — drawn from real user sessions and onboarding calls — alongside answers to the most common questions and points of friction when configuring, integrating, and operating agents on the Alludium platform. Questions and guidance are grouped by theme so you can navigate directly to what's relevant. If your question isn't covered here, contact the team at and include as much context as possible to help us respond quickly. *** ### Core Principles Four principles consistently emerge from the way the most successful users operate on the platform: 1. **Agents work best when simple** — focused, single-purpose agents outperform complex multi-function ones 2. **Prompt clarity drives output quality** — well-structured prompts unlock the best performance from your agents 3. **Integrations reward careful setup** — taking time to configure connections correctly ensures smooth, reliable operation 4. **Iterative testing accelerates results** — build small, test early, then scale with confidence *** ### Agent Design #### Write Clear, Structured Prompts The clearer your prompt, the better your agent performs. A well-structured prompt should specify: * **Goal** — what the agent is trying to achieve * **Inputs** — what data or documents to use * **Steps** — the process the agent should follow * **Constraints** — what the agent must not do * **Output format** — how results should be presented Think of prompts as instructions to a skilled analyst: the more precise the brief, the better the output. Clear prompts produce sharper responses, ensure workflow steps are followed correctly, and improve document generation quality. **Tell your agent what not to do — it matters as much as what to do.** Explicitly stating what an agent should avoid is just as important as describing what it should produce. Without clear constraints, agents may make reasonable but unwanted choices — summarising when you wanted bullet points, including caveats you didn't ask for, or going beyond the defined scope. Constraints give your agent boundaries that make its behaviour consistent and predictable. For example, rather than just writing *"Summarise this report"*, write: *"Summarise this report in three bullet points. Do not include recommendations, do not reference page numbers, and do not exceed 100 words."* **Provide a real example of the output you want.** One of the most effective ways to improve output consistency is to include a concrete example of exactly what a good response looks like. Agents that have a real example to reference produce more reliable, better-formatted results — particularly for tasks involving structured documents, emails, or reports. For example, if you want a weekly status update in a specific format, paste a completed example directly into the prompt and instruct the agent to follow it precisely. This removes ambiguity about tone, structure, length, and level of detail far more effectively than a description alone. **Q: How do I make my agent more conversational?** Use the Agent Configurator chat interface to specify: *"Make responses more conversational and engaging, ask follow-up questions when appropriate."* **Q: How do I prevent my agent from discussing certain topics?** In the agent configuration, specify: *"Do not provide information about \[topic]. Instead, direct users to \[alternative resource]."* *** #### Keep Agent Tasks Focused Agents deliver their best results when given a clearly defined, single purpose. Design focused agents wherever possible: | Good | Avoid | | ------------------ | -------------------------------------------------------- | | Email triage agent | "Research, summarise, draft emails, and manage calendar" | | Deal room creator | "Deal analysis + folder creation + research + messaging" | Focused agents execute faster, make more efficient use of the context window, and are straightforward to refine over time. *** #### Separate Development and Production Agents Conflating build and run environments is a frequent source of confusion. Maintain a clear separation: * **Development agents** — for testing, prompt experiments, and iteration; not shared * **Production agents** — stable, shared with the workspace, with automations enabled where needed **Q: What is the difference between Agent Builder and My Agents?** **Agent Builder (Agent Configurator)** * Used to create or modify agents * Starts from a clean state every time * Focuses on defining scope, inputs, tools, outputs, and constraints Think of this as the **agent factory**. **My Agents** * Used to run and interact with agents * Each agent has its own conversation history * Supports document upload (if configured) Think of this as the **execution environment**. **Q: Why does the Agent Configurator reset every time?** The Configurator is designed to build agents deterministically, avoid accidental carry-over from previous builds, and force clarity on scope and dependencies. This ensures agents behave consistently once deployed to My Agents. **Q: Why can't I do everything in one chat?** Each agent maintains its own memory, tools, and permissions. Using one shared chat for multiple agents and workflows creates ambiguity around which agent owns the conversation, which tools are available, and which documents apply. *** #### Start with Templates Rather than building from scratch, begin with Alludium's starter agents or templates, customise the prompt, and gradually add tools as needed. This significantly reduces onboarding friction and makes it easier to isolate what's driving agent behaviour. *** ### Building and Testing #### Deploy Agents Iteratively The most successful users follow a build → test → refine loop rather than launching fully-configured agents immediately: 1. Create a minimal agent 2. Test manually with a small dataset 3. Add integrations 4. Add automations where needed 5. Deploy to workspace 6. Collect feedback and refine #### Test with Small Datasets First Starting with a small dataset makes it straightforward to validate agent behaviour before scaling up: 1. Run the agent against 1–3 files 2. Confirm correct behaviour 3. Gradually increase dataset size This makes it easy to confirm whether the prompt, tools, and integrations are all working as expected — before applying the agent to a larger workload. *** ### Integrations and Connections #### Configure Integrations Carefully Getting integrations right at the outset ensures reliable, smooth operation. When connecting tools: * Ensure correct permissions are granted * Share the full OAuth window during setup * Reconnect integrations if errors occur Integrations requiring particular care include Google Drive, Gmail, Slack, Zoom, and calendar tools. **Q: Which platforms can I integrate with?** Alludium supports many platforms either directly via their native MCP or via the integrated Pipedream application. Search for available integrations on the **Integrations** page. If a required integration doesn't appear, contact to request it. *** #### Prefer Structured Data Sources Over PDFs PDF processing is inherently less reliable than structured formats. Where possible: | Prefer | Avoid | | -------------------------- | --------------------- | | Google Docs | Large or complex PDFs | | Structured datasets / CSVs | Scanned documents | | DOCX files | Image-based files | If PDFs are unavoidable, keep folder sizes small and convert to DOCX where possible. **Q: Can I upload my own documents?** Yes. Documents can be uploaded directly in your agent chat, attached to a project, or uploaded through **Files** for reuse. **Q: Why don't I see the upload button in chat?** Common reasons: * You are still in the Agent Configurator rather than My Agents * The agent was not configured to accept files * Uploads are agent-scoped, not global *** ### Automations #### Set Automation Frequency Carefully Overly frequent automations cause unnecessary executions. Recommended frequencies by use case: | Use Case | Recommended Frequency | | ---------------- | --------------------- | | Email monitoring | Daily | | Research agents | Daily | | Deal monitoring | Daily or weekly | Avoid 30-minute automations unless the use case genuinely requires near-real-time execution. *** ### Workspace and Deployment #### Follow the Correct Deployment Sequence A common confusion point is sharing agents before they are properly deployed. The correct workflow is: 1. Build agent in development 2. Test with sample data 3. Deploy agent 4. Share to workspace *** ### Models and Reasoning **Q: What does "reasoning configuration" mean?** Some models (e.g., Anthropic) allocate a reasoning budget — tokens dedicated to thinking through a response. Increasing the reasoning configuration slider gives the model more tokens to work with before producing an output. **Q: Do I need to understand all the advanced parameters (preamble, effort, verbosity, etc.)?** Not necessarily. Non-technical users can use the simple reasoning slider or ignore the technical configuration entirely and still achieve strong results. *** ### Monitoring and Debugging #### Check Logs Before Escalating The platform provides detailed logging at every level, making it straightforward to understand agent behaviour and resolve questions quickly. Before contacting support, check: * **Automation execution history** — to confirm whether an automation ran and when * **Integration logs** — to identify connection errors * **Agent conversation history** — to review what the agent received and returned These three sources provide full visibility into agent behaviour and resolve the vast majority of questions without needing to contact support. *** ### Support and Feedback **Q: How do I report bugs or give feedback?** Email with your bug report or feedback. Include screenshots and videos where possible. **Q: What information should I include when reporting an issue?** Please include: * Agent ID (the URL from the address bar when in the Agent Configurator for that agent) * Agent Name * Your User ID * Steps to reproduce the issue * Date and time of the issue * Error messages or screenshots/videos * Browser and device information **Q: How will I be notified about issue status?** You'll receive email updates from as your issue is reviewed and resolved. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://alludium.gitbook.io/alludium-docs/15.-best-practices-troubleshooting-and-faqs.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.