> ## 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.
# Bothive Beginner Handbook
> A complete, plain-language guide to building, testing, deploying, and operating Bothive agents.
This handbook is for somebody who has never built an AI agent before. Read it from top to bottom the first time. Later, use the headings as a reference when you are stuck.
Create your first useful worker.
Give it one safe capability.
Release it with a rollback path.
Start with **Build Your First Agent**, then return here when you have a draft.
Start with **Connect Your First Tool** and import your OpenAPI JSON or YAML.
Start with **Organisation Workspaces** and use staged shared-bot changes.
You can follow this guide without writing code. The builder and HiveMind are designed to let you start in plain language and inspect code only when you need more control.
## What Bothive is
Bothive helps you build software agents that can understand requests, use tools, remember useful context, and complete work. You do not need to start with a framework, a server, or a large codebase.
An agent is a worker with a job. A support agent answers customer questions. A research agent collects evidence. A scheduling agent watches for work and runs at the right time. A content agent drafts material in a consistent voice.
The dashboard is the place where you manage those workers. HiveMind helps you describe what you want. The builder lets you inspect and edit the behavior. The playground lets you test it. Deployments let you release it. Observability lets you understand every run.
## The words you will see
### Agent
An agent is the complete worker: its instructions, tools, memory, schedules, channels, and deployment versions.
### Bot
Bothive uses bot and agent interchangeably in the dashboard. A bot is not a chat bubble only; it can work through APIs, schedules, channels, and background jobs.
### HiveMind
HiveMind is the conversational builder. You explain the outcome in normal language. It asks important questions, suggests integrations, proposes a plan, and generates a draft.
### HiveLang
HiveLang is Bothive's readable configuration language. It describes the agent's identity, capabilities, memory, schedules, and behavior. You can use HiveMind without learning HiveLang, but the builder shows it when you need control.
### Capability
A capability is one thing an agent can do. Examples include searching Gmail, reading a Notion page, creating a task, calling a custom API, or writing a memory.
### Integration
An integration connects an external service to Bothive. It stores the connection and describes the capabilities that service exposes.
### Memory
Memory is durable context that should survive a single conversation. Good memory includes a customer's preference, a verified business rule, a voice profile, or a last-processed date.
### Run
A run is one attempt by an agent to handle an input. Every run should have a status, a trace, and a clear result.
### Trace
A trace is the timeline of one run. It helps you see the request, model, capabilities, approvals, retries, memory events, schedule origin, and result.
### Deployment
A deployment is a version of an agent released to an environment. Bothive supports preview, staging, and production versions.
### Organisation
An organisation is a shared workspace for people, teams, bots, policies, and audit history.
### Team
A team is a focused group inside an organisation. Use teams for a product squad, a hackathon track, a department, or a customer project.
## First login
1. Open the Bothive dashboard.
2. Sign in or create an account.
3. Read the dashboard summary before creating anything.
4. Notice the agents list, recent activity, and next-step cards.
5. Do not worry about every menu item yet.
6. Start with one small outcome.
The best first outcome is specific and testable. “Help my business” is too broad. “Answer order-status questions using our order API and never change an order without approval” is a good start.
## Plan your first agent
Before opening HiveMind, answer five questions.
1. Who will use the agent?
2. What input will they give it?
3. What useful result should come back?
4. Which systems does it need to read?
5. Which actions must wait for approval?
Write one sentence for the job.
Write one sentence for what success looks like.
Write one sentence for what the agent must never do.
Choose one channel for the first test.
Choose one example input that is realistic.
## Build with HiveMind
Open HiveMind from the dashboard.
Describe the outcome instead of listing technical features.
Good request:
> Build a customer-support agent that searches our help content, checks order status from our API, remembers the customer's preferred name, and drafts an email for approval when a human follow-up is needed.
Weak request:
> Make an AI bot with lots of tools.
HiveMind may ask a question before generating the draft. Answer it directly. If you are unsure, choose the safest reasonable option and say what you assumed.
Review the suggested integration list.
Review which actions are read-only.
Review which actions write data.
Review which actions need approval.
Review the suggested memory.
Review the suggested schedule.
Approve the plan only when it describes the job you actually want.
## Understand the builder
The builder has an editor and configuration panels.
The identity describes who the agent is.
The system prompt describes its behavior.
Capabilities describe what it can call.
Memory describes what it can recall or remember.
Schedules describe proactive work.
Channels describe where people interact with it.
The test area lets you try the current draft.
The publish or deploy action creates a version.
Do not treat generated code as automatically correct. Generated code is a draft that still needs review.
## Write a useful identity
Give the agent a name that explains its job.
Write a short description for teammates.
State who the agent serves.
State what it is responsible for.
State what it is not allowed to pretend.
Tell it to ask when a required fact is missing.
Tell it to distinguish a draft from a completed action.
Tell it to be concise if the channel is a widget or SMS.
Tell it to include evidence when it uses external data.
## Add memory carefully
Use memory for stable facts.
Use memory for preferences.
Use memory for approved voice guidance.
Use memory for last-processed checkpoints.
Use memory for a known customer context.
Do not store passwords in memory.
Do not store API keys in memory.
Do not store a full sensitive conversation forever.
Do not save a guess as a verified fact.
Ask the agent to confirm important memories before saving them.
Give memory keys clear names such as `voice_profile`, `preferred_timezone`, or `last_invoice_sync`.
## Connect a built-in integration
Open Integrations.
Choose the provider.
Read the requested permissions.
Connect the account.
Return to the agent builder.
Select the capability.
Test a read action first.
Confirm the result is from the expected account.
Only then consider a write action.
If the provider asks for a scope you do not understand, pause and investigate it before approving.
## Connect a custom API
Open Connect your API.
Give the service a clear name.
Enter the base URL.
Choose no auth, API key, or bearer auth.
Add one endpoint.
Use an operation name such as `getOrderStatus`.
Describe the endpoint in plain language.
Declare required parameters.
Import OpenAPI JSON or YAML when you have a specification.
Use a documentation URL when the spec is hosted online.
Test every endpoint.
Use safe test data.
Connect the integration only after the tests pass.
Never paste a production secret into a public issue or prompt.
## Choose approval boundaries
Read actions can usually run automatically.
Draft actions should produce reviewable work.
Send actions should usually require approval.
Publish actions should usually require approval.
Delete actions should require approval.
Payment actions should require approval.
Invite actions should require approval.
Schedule changes should require permission.
Tell the agent what approval means.
Tell it what to show in the approval request.
Tell it what to do when approval is denied.
An approval is not a suggestion. It is a boundary before the external side effect.
## Test in the playground
Start with the happy path.
Try a missing parameter.
Try an unknown customer.
Try an ambiguous request.
Try a request that should be denied.
Try a write action.
Confirm the action pauses.
Open Autopilot.
Read the payload summary.
Approve only if the target and operation are correct.
Check the final status.
Open the trace.
Repeat the test after every meaningful change.
## Read the overview page
The Overview page is your operating picture.
Health shows whether the agent needs attention.
Metrics show runs, success rate, users, and latency.
Recent activity links to traces.
Environment posture shows preview, staging, and production.
Channels show where the agent is connected.
Schedules show proactive work.
Use Overview before opening a deeper page.
## Read a trace
Open a run from Recent runtime activity.
Read the status first.
Check the trigger and channel.
Check the session.
Check the model and provider.
Check token usage and estimated cost.
Check prompt and HiveLang versions.
Read the timeline from top to bottom.
Look for approval events.
Look for tool calls.
Look for memory events.
Look for schedule events.
Read the redacted request.
Read the redacted response.
Read the error and retry state.
Do not debug from the final error alone; the first failed event often explains the real cause.
## Deploy safely
Save the draft.
Deploy to preview.
Test the real channel.
Invite a teammate to review.
Promote to staging.
Run the readiness report.
Confirm the integrations are connected.
Confirm required secrets exist.
Confirm approval gates work.
Confirm a rollback target exists.
Promote to production.
Watch the first production runs.
Keep the previous version available.
## Roll back
Open Deployments.
Find the last known-good version.
Confirm its environment.
Read its commit message.
Confirm the rollback target.
Start the rollback.
Open the resulting deployment record.
Open a new production trace.
Confirm the runtime behavior is restored.
After recovery, fix the draft separately.
Never edit production manually to hide an incident.
## Create an organisation
Open Organisations from the dashboard.
Choose Create organisation.
Give it a meaningful name.
Add a short description.
Open the organisation details page.
Invite the first collaborators.
Create teams for focused work.
Set the default member role.
Decide whether members can change shared bots.
Decide whether production needs admin approval.
Review the audit trail.
## Work with a team
Create a team for a clear project.
Add only the people who need access.
Create or assign a shared bot.
Ask contributors to stage changes.
Review the parent version.
Compare the change.
Run tests.
Commit the reviewed change.
Deploy through preview.
Use the audit trail to explain what changed.
This workflow works for an enterprise squad and a weekend hackathon.
## Choose roles
Owners manage the organisation.
Admins manage members, policy, and production operations.
Members build and operate according to their permissions.
Viewers inspect the workspace without changing it.
Start with the least access that lets somebody do their job.
Give deploy production permission only to trusted operators.
Give schedule permission only to people who understand proactive work.
Review access when somebody changes teams.
Remove access when somebody leaves the project.
## Use literal voice
Open the bot Identity page.
Find Literal voice.
Connect ElevenLabs in Integrations for premium voice audio.
Load available voices.
Choose a voice.
Choose a model.
Save the profile.
Turn voice on.
Preview a sentence.
Use the playground Voice action on an assistant response.
If ElevenLabs is unavailable, Bothive can use the browser voice for local previews.
Remember that browser voice availability depends on the device and browser.
### Voice billing
Bothive meters generated voice in the same platform usage ledger as other hosted services. The owner of the bot is the billed account.
| Voice activity | What is measured | Where to see it |
| -------------------------- | -------------------------------------------------------- | --------------------------------- |
| Identity preview | Generated characters, rounded into 1,000-character units | Billing and Usage |
| Playground Voice action | Generated characters and linked run | Billing, Usage, and the run trace |
| Browser fallback | No ElevenLabs provider usage; local browser speech only | Local preview notice |
| Connected ElevenLabs voice | Provider, voice ID, model, and character count | Voice profile and usage metadata |
Connect ElevenLabs before enabling premium voice in a production channel. Browser speech is useful for local testing but is not a hosted audio delivery service.
Open Integrations and connect your ElevenLabs API key.
Open the agent Identity page, load voices, and choose a profile.
Save the profile and use Preview to generate a short test.
Open Billing or Usage to see generated characters and the billable voice amount.
## Common problems
### The agent gives a vague answer
Make the job narrower.
Add an example.
Connect the missing source of truth.
Tell it what to do when data is missing.
Test again.
### The tool is not called
Check the integration connection.
Check the capability name.
Check required parameters.
Check the agent instructions.
Check the trace for routing evidence.
### An action is waiting
Open Autopilot.
Read the risk and payload.
Approve, deny, or leave it waiting.
Do not approve an unfamiliar target.
### Voice does not play
Check that voice is enabled.
Check that ElevenLabs is connected.
Try Preview in Identity.
Check browser autoplay permissions.
Use the browser fallback for a local test.
Check the browser console only after the basic steps.
### A deployment failed
Open the deployment record.
Read the readiness blockers.
Open the first failed trace.
Check secrets and integrations.
Fix the draft.
Retry in preview.
### A teammate cannot deploy
Check their organisation role.
Check `deploy_production` permission.
Check the organisation deployment policy.
Ask an admin to promote when policy requires it.
## Safety checklist
Use test credentials for preview.
Never store secrets in prompts.
Never trust an unverified external response.
Require approval for destructive actions.
Keep production permissions narrow.
Review audit events.
Keep rollback versions available.
Redact sensitive user data from logs.
Test failure behavior, not only success behavior.
Tell users when an answer is uncertain.
## Hackathon checklist
Choose one user problem.
Create one team.
Invite the builders.
Build one agent.
Connect one real tool.
Use preview deployment.
Prepare three demo inputs.
Test the approval flow.
Save a rollback version.
Write down the architecture.
Show the trace in the demo.
Keep a backup recording of the successful run.
## Enterprise checklist
Define ownership.
Define roles.
Define production approval.
Define required integrations.
Define secret handling.
Define retention expectations.
Define escalation paths.
Define incident response.
Define rollback ownership.
Review readiness before launch.
Review traces after launch.
Review permissions monthly.
## Where to go next
Read Build Your First Agent for a shorter guided path.
Read Connect Your First Tool for API setup.
Read Deploy Your First Agent for environments.
Read Read Your First Trace for debugging.
Read Organisation Workspaces for team governance.
Read Team Shared Bots for collaboration.
Read Custom Integrations for advanced API contracts.
Read Observability for production operations.
You do not need to learn everything at once. Build one useful worker, test it carefully, and add capability only when the next user outcome is clear.