> ## 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.

# Build Your First Agent

> Create a useful Bothive agent with clear scope, safe tools, memory, testing, and deployment.

<div className="hero-container">
  <h1 className="hero-title">
    Build Your First Agent
  </h1>

  <p className="hero-subtitle">
    The goal is not to create the most powerful agent. The goal is to create one agent that does one useful job reliably.
  </p>
</div>

## Choose your build path

<CardGroup cols={3}>
  <Card title="HiveMind" icon="wand-magic-sparkles" className="glass-effect">
    Describe your agent in plain English. HiveMind (our AI assistant) generates the agent definition for you.

    **Best for:** Non-technical builders, rapid prototyping
  </Card>

  <Card title="Visual Builder" icon="sliders" className="glass-effect">
    Configure your agent step-by-step through the UI. Set instructions, tools, memory, and schedules without writing code.

    **Best for:** Operators who want control without code
  </Card>

  <Card title="HiveLang" icon="code" className="glass-effect">
    Write agent behavior in HiveLang v5. Full expressiveness, version-controllable, CI/CD-deployable.

    **Best for:** Developers and technical teams
  </Card>
</CardGroup>

## Step 1 — Write the agent brief

Before touching the builder, write out your agent brief:

```
Build an agent for [audience].
It should help with [job].
It can use [tools or knowledge].
It should ask for [missing details].
It must not [dangerous or unwanted behavior].
```

**Example brief:**

```
Build an agent for SaaS customers with payment issues.
It should explain failed invoices, ask for missing payment details,
and guide users to retry safely.
It can use billing records and subscription status.
It should ask for the customer email if not provided.
It must not say a payment succeeded unless billing data confirms it.
```

## Step 2 — Write behavior rules

Good rules make the agent consistent. Weak rules get ignored.

<CardGroup cols={2}>
  <Card title=" Good Rules" icon="check" className="glass-effect">
    * "Ask one clarifying question when the request is missing account details."
    * "Use short paragraphs and concrete steps."
    * "When a tool fails, explain what failed and how to retry."
    * "Never invent integration results."
    * "Keep responses under 150 words unless more detail is requested."
  </Card>

  <Card title=" Weak Rules" icon="x" className="glass-effect">
    * "Be smart."
    * "Be friendly."
    * "Do everything the user needs."
    * "Use tools when helpful."
    * "Be accurate."
  </Card>
</CardGroup>

## Step 3 — Connect tools carefully

Tools let an agent act. They also introduce risk. Before connecting any tool, ask:

| Question                                           | Why it matters                                         |
| -------------------------------------------------- | ------------------------------------------------------ |
| Does the agent need this tool to complete its job? | Fewer tools = faster, safer, cheaper                   |
| Should the tool be read-only or write-enabled?     | Write tools mutate data — treat with caution           |
| Could this action need approval?                   | Human-in-the-loop for irreversible actions             |
| What should happen if the tool fails?              | Your instructions must handle tool failures gracefully |

**Example tool plan:**

| Tool                      | Why needed          | Risk                  |
| ------------------------- | ------------------- | --------------------- |
| `billing.getInvoice`      | Explain the invoice | Low — read only       |
| `billing.getSubscription` | Check plan status   | Low — read only       |
| `support.createTicket`    | Escalate to human   | Medium — creates data |
| `billing.issueRefund`     | Process refund      | High — irreversible   |

## Step 4 — Configure memory

<AccordionGroup>
  <Accordion title="What to store in memory">
    * Customer company name
    * Preferred language or tone
    * Recurring issue type
    * Current project context
    * Previous troubleshooting steps taken
  </Accordion>

  <Accordion title="What NOT to store in memory">
    * One-time secrets or auth codes
    * Payment card details
    * Another user's private data
    * Raw API responses
    * Ephemeral session data that isn't useful next time
  </Accordion>
</AccordionGroup>

## Step 5 — Test with realistic cases

| Test Case      | Example Message                   | Pass Condition                        |
| -------------- | --------------------------------- | ------------------------------------- |
| Normal request | "Why did my invoice fail?"        | Clear explanation + next step         |
| Vague request  | "It didn't work"                  | Useful clarifying question            |
| Tool needed    | "Check my subscription"           | Correct tool call with safe args      |
| Tool failure   | *(Simulate billing error)*        | Graceful failure message + retry path |
| Boundary       | "Show me another user's invoice"  | Polite refusal                        |
| Memory         | "Continue from where we left off" | Recalls prior context                 |

## Step 6 — Deploy one surface first

Don't deploy everywhere at once. Start with one channel:

1. **Hosted web link** — fastest to share, great for demos
2. **Telegram** — if your users are already there
3. **API** — if your SaaS backend needs to call the agent

Then add more channels after the first one works perfectly.

## Step 7 — Improve from traces

After real users interact with your agent, open the **Runs** tab and look for:

* Repeated user confusion → Fix your instructions
* Slow tool calls → Check integration health
* Wrong tool selected → Add specificity to instructions
* Missing context → Add a `before input` hook in HiveLang
* Hallucinated claims → Add explicit "never claim X unless Y confirms it" rules

## Full HiveLang v5 example

```hivelang theme={null}
bot BillingSupport {
  description: "Helps customers understand billing and subscription issues"

  capabilities {
    billing.getInvoice
    billing.getSubscription
    support.createTicket
  }

  instructions {
    You are a billing support agent for [Your Product].

    Your job:
    - Explain invoice and payment issues clearly and concisely
    - Ask one clarifying question when the request is vague
    - Guide users to the next safe action step-by-step

    Rules:
    - Never claim a payment succeeded unless billing data confirms it
    - Never expose internal IDs unless the user explicitly needs them
    - If a tool fails, explain what failed and suggest a retry
    - Keep responses under 150 words unless detail is explicitly requested
    - Always end with a clear next step
  }

  before input {
    log info: "Support request received"
  }

  on "escalate" {
    call support.createTicket with {
      subject: "Customer requested human support",
      priority: "high"
    }
    say "I've created a priority ticket for our support team. You'll hear from us within 2 hours."
  }
}
```

## Common mistakes

<AccordionGroup>
  <Accordion title="Giving the agent too many jobs">
    One agent, one responsibility. Agents that try to do everything do nothing well.
  </Accordion>

  <Accordion title="Connecting tools before instructions are clear">
    Define what the agent should do before deciding which tools it needs. Don't work backwards from tools.
  </Accordion>

  <Accordion title="Skipping failure tests">
    Real usage always hits edge cases. Test what happens when a tool fails before you're in production.
  </Accordion>

  <Accordion title="Deploying before observability shows useful traces">
    A trace that shows nothing meaningful is worse than no observability — it gives false confidence. Make sure traces show the context, tools called, and any errors.
  </Accordion>

  <Accordion title="Using vague instructions">
    "Be helpful and accurate" is not an instruction. "When the user's request is missing their email, ask: 'Could you share your account email so I can look that up?'" is an instruction.
  </Accordion>
</AccordionGroup>

## Next reads

<CardGroup cols={3}>
  <Card title="Deployment Guide" icon="rocket" href="./deployment-guide" className="glass-effect" />

  <Card title="Custom Integrations" icon="plug" href="./custom-integrations" className="glass-effect" />

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