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

# Production Deployment Guide

> Everything you need to go from a working agent to a production-grade deployment.

<div className="hero-container">
  <h1 className="hero-title">
    Production Deployment Guide
  </h1>

  <p className="hero-subtitle">
    A working agent in the playground is not a production agent. This guide covers what it takes to deploy reliably.
  </p>
</div>

<Warning>
  **Don't skip this guide.** The most common failure mode is deploying a "good enough" agent that breaks in edge cases real users hit within the first hour. Production readiness is a checklist, not a feeling.
</Warning>

## The production readiness standard

Your agent is production-ready when:

<CardGroup cols={2}>
  <Card title="It handles failures gracefully" icon="shield" className="glass-effect">
    When a tool fails, the agent explains what happened and offers a retry path — it doesn't crash or hallucinate an answer.
  </Card>

  <Card title="Traces are meaningful" icon="chart-line" className="glass-effect">
    Every run produces a trace that tells you what happened, why, and how to fix it if something went wrong.
  </Card>

  <Card title="Memory works end-to-end" icon="brain" className="glass-effect">
    A user can come back hours later and the agent remembers the important context from their last session.
  </Card>

  <Card title="Limits are configured" icon="gauge" className="glass-effect">
    Rate limits, cost caps, and usage limits are set before real users arrive — not after.
  </Card>
</CardGroup>

## Deployment steps

<Steps>
  <Step title="Finalize your HiveLang definition">
    Your bot's HiveLang file should be in version control. Every deployment should come from a committed file, not a manual edit in the UI.

    ```hivelang theme={null}
    bot ProductionBot {
      description: "Production support agent for AcmeSaaS"

      capabilities {
        knowledgebase.search
        billing.getSubscription
        support.createTicket
      }

      instructions {
        You are a production support agent for AcmeSaaS.

        Priority order for resolving requests:
        1. Search the knowledge base first
        2. If KB has no answer, check billing status
        3. If still unresolved, create a support ticket

        Rules:
        - Never guess — only assert what tools confirm
        - Always end with a next step
        - Escalate if the user is frustrated after 2 turns
      }

      before input {
        log info: "Production request: {input}"
      }
    }
    ```
  </Step>

  <Step title="Configure environment variables">
    Set all required secrets in **Settings → Environment Variables**. Never hardcode them in HiveLang.

    | Variable             | Used for                |
    | -------------------- | ----------------------- |
    | `OPENAI_API_KEY`     | Model inference         |
    | `SLACK_BOT_TOKEN`    | Slack channel           |
    | `TELEGRAM_BOT_TOKEN` | Telegram channel        |
    | `CUSTOM_API_KEY`     | Your custom integration |
  </Step>

  <Step title="Set rate limits">
    In your bot settings → **Usage Limits**:

    * **Max runs/user/hour** — prevent abuse
    * **Max runs/day** — protect your budget
    * **Max tokens/run** — cap response length and cost

    Start conservative. You can loosen limits after observing real traffic.
  </Step>

  <Step title="Deploy to production">
    Using the dashboard:

    1. **Bot → Deploy → Production**
    2. Review the parse output for errors or warnings
    3. Confirm deployment

    Using the API:

    ```bash theme={null}
    curl -X POST https://api.bothive.cloud/v1/bots/{bot_id}/deploy \
      -H "Authorization: Bearer bh_sk_xxxxxxxxx" \
      -d '{"hivelang": "...", "environment": "production"}'
    ```
  </Step>

  <Step title="Deploy your first channel">
    Connect one channel and verify it end-to-end with real messages before adding more. Confirm:

    * Message delivery works
    * Session persistence works across 2+ messages
    * Tool calls succeed
    * Traces appear in the Runs tab
  </Step>

  <Step title="Set up monitoring">
    In **Settings → Alerting**, configure:

    * High error rate alert (>10% failures in 1 hour → notify via Slack or email)
    * Slow latency alert (P95 > 5s)
    * Tool failure spike (same tool fails 3+ times in 10 minutes)
  </Step>
</Steps>

## Environment checklist

Before going live, confirm each item:

| Check                            | Command / Location               |
| -------------------------------- | -------------------------------- |
| All env vars set                 | Settings → Environment Variables |
| Bot deploys without parse errors | Bot → Deploy → check output      |
| Playground passes all test cases | Bot → Playground                 |
| Rate limits configured           | Settings → Usage Limits          |
| One channel deployed and tested  | Channels tab                     |
| Alerting configured              | Settings → Alerting              |
| Observability traces visible     | Bot → Runs                       |

## Rollback strategy

If a production deployment breaks:

<Steps>
  <Step title="Identify the issue">
    Open **Runs → filter by status: error** → read the trace.
  </Step>

  <Step title="Roll back immediately">
    In **Bot → Deployments**, click the last stable deployment → **Rollback**. This takes \~10 seconds.
  </Step>

  <Step title="Fix in staging">
    Use a staging environment to fix the issue. Only redeploy to production when staging is verified.
  </Step>
</Steps>

## Common production issues

<AccordionGroup>
  <Accordion title="Agent gives inconsistent answers">
    Increase instruction specificity. Add explicit rules for edge cases you've observed in traces. Consider lowering the model temperature.
  </Accordion>

  <Accordion title="Tool calls fail in production but work in staging">
    Production OAuth tokens may have different scopes or may have expired. Re-authenticate each integration in the production environment settings.
  </Accordion>

  <Accordion title="Memory not persisting between sessions">
    Check that you're passing a stable `X-Session-ID` header (for API channel) or that the Telegram/Slack user IDs are consistent. Ephemeral memory clears after each session by design.
  </Accordion>

  <Accordion title="High latency on first message">
    This is usually cold-start on the integration layer. Add a `before input` hook that pre-fetches common data to warm up the context before the model runs.
  </Accordion>
</AccordionGroup>

## Next reads

<CardGroup cols={3}>
  <Card title="Deploy to Channels" icon="signal" href="./deploy-to-channels" className="glass-effect" />

  <Card title="Launch Checklist" icon="circle-check" href="./launch-checklist" className="glass-effect" />

  <Card title="Observability" icon="chart-line" href="../concepts/observability" className="glass-effect" />
</CardGroup>