> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatropic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Best practices

> Recommendations for high-quality agent configuration

A few habits make the difference between an agent that answers well and one that frustrates customers:

* Write clear action descriptions, because they decide when the agent calls each tool
* Keep knowledge sources focused and up to date
* Start a **New test session** before each test run so earlier turns do not skew results

## Knowledge

* **Split large documents** into focused sources (returns policy, shipping, billing) so retrieval finds the right passage
* **Use descriptive titles** on **Text** sources to make debugging easier
* **Re-crawl or re-upload** when content changes, since stale chunks cause outdated answers
* **Remove deprecated content** instead of leaving conflicting sources in place

## Actions

* **Treat the description as "when to call".** Write it like an instruction to a colleague: *"Search records by reference when the user asks about order or ticket status."*
* **Minimize required parameters.** The agent asks follow-up questions for missing fields, but fewer fields means faster resolution.
* **Test with the action test panel** on the action detail page before enabling it in production.
* **Never store secrets** in dashboard-visible URLs. Use saved tokens or a server-side proxy instead.

## Instructions & branding

* For Customer Support agents, instructions are generated from your sources. To change behavior, add or improve documents rather than editing instructions directly.
* Set a welcome message and 3 to 5 suggested prompts that mirror real user intents.
* Match the tone to your brand, whether that is formal support or a casual assistant.

## Before go-live

<Steps>
  <Step title="Run guardrails">
    Configure topics, PII filters, rate limits, and frustration escalation under **Agent settings > Security**.
  </Step>

  <Step title="Test edge cases">
    Start a **New test session** and try out-of-scope questions, multi-turn slot-filling, and escalation phrases.
  </Step>

  <Step title="Configure handoff">
    Add an [Escalate to human](/user-guides/actions/escalate-to-human) action. If you use WhatsApp, configure handoff under **Actions > Integrations**.
  </Step>

  <Step title="Deploy to staging">
    Use the demo links on the **Deploy > Chat widget > Embed** tab (website widget or inline panel), or a sandbox WhatsApp number, before sending production traffic. Confirm your test messages appear in **Chat logs**.
  </Step>
</Steps>

<CardGroup cols={2}>
  <Card title="Guardrails" icon="shield" href="/user-guides/settings/guardrails">
    Safety controls and fallbacks.
  </Card>

  <Card title="Use-case recipes" icon="list" href="/user-guides/recipes/helpdesk">
    Starter patterns for common deployments.
  </Card>
</CardGroup>