Set up Bland with an AI agent

name: blandai
description: Use when building, configuring, testing, and deploying AI voice
  agents that make and receive phone calls. Reach for this skill when working
  with agent creation, tool integration, knowledge bases, environment
  management, call dispatch, and conversation monitoring.
metadata:
  mintlify-proj: blandai
  version: "1.0"

Bland AI Voice Agents Skill

Product summary

Bland AI is a platform for building, testing, and deploying AI voice agents that handle phone calls. Agents are configured in the dashboard at v2.app.bland.ai or programmatically via the Agents API at https://api.bland.ai/v2/agents. An agent consists of a prompt (what it does), system prompt (how it sounds), tools (APIs it calls), knowledge sources (documents it answers from), and pathways (branching conversation flows). Agents run on three environments: development (editing), staging (testing), and production (live calls). Key files and concepts: agent versions (immutable snapshots), environments (dev/staging/production pins), tools (webhook, custom code, or integration), knowledge sources (files, websites, text, or synced docs), and dispatches (phone numbers, batches, triggers). Primary docs: https://docs.bland.ai

When to use

Use this skill when:

• Building agents: Creating new agents, writing prompts, adding tools and knowledge, configuring pathways
• Integrating external systems: Connecting APIs via webhook tools, setting up CRM integrations, storing secrets
• Managing knowledge: Uploading documents, attaching sources to agents, testing retrieval, managing gaps
• Publishing and promoting: Moving agents through dev → staging → production, running evaluations, rolling back
• Dispatching calls: Attaching phone numbers, running batch calls, setting up triggers, configuring channels
• Monitoring conversations: Reading transcripts, analyzing call logs, checking tool performance, debugging agent behavior
• API automation: Creating agents programmatically, managing versions, publishing, promoting via REST endpoints

Quick reference

Agent structure

Component	Purpose	Where to configure
Prompt	What the agent does, goals, instructions	Agent builder, Prompt tab
System prompt	Tone, personality, communication style	Agent builder, Prompt tab
Variables to extract	Key-value pairs agent pulls from conversation	Agent builder, Prompt tab
Pathways	Branching conversation flows for specific tasks	Agent builder, Pathways section
Tools	APIs the agent calls (webhook, code, integration)	Tools page, tag with @ in prompt
Knowledge	Documents agent answers from (files, web, text)	Knowledge page, attach or tag with @
Settings	Voice, language, memory, metadata, recording	Agent builder, Settings tab

Environments and deployment

Environment	Purpose	Editable	Calls run	How to move
Development	Your working copy	Yes	Never	Save work here
Staging	Testing before production	No	Only if explicitly targeted	Publish from Dev
Production	Live calls	No	By default	Promote from Staging

Tool types

Type	Use when	Example
Webhook	Calling your own API or third-party HTTP endpoint	POST to your backend, GET from external API
Custom code	Single HTTP call is not enough; need reshaping, combining, or calculation	Combine two API responses, transform data
Integration	Acting on a connected service (CRM, calendar, Slack)	Create contact in Salesforce, check Cal.com availability

Knowledge source types

Type	Use when	Limit
Upload	Adding files (PDF, TXT, CSV, JSON, DOCX)	10 MB per file, 10 files at a time
Website	Scraping URLs or discovering from sitemap	Auto-syncs daily if enabled
Text	Pasting content directly	1 million characters
Integration	Syncing from Notion or Google Docs	Read-only in Bland, edit in source app

Common API endpoints

Endpoint	Purpose
POST /v2/agents	Create agent
POST /v2/agents/{id}/versions	Save version
POST /v2/agents/{id}/publish	Publish to staging
POST /v2/agents/{id}/promote	Promote to production
POST /v1/calls	Make outbound call with agent_id
POST /v1/calls-agent	Make call with agent (legacy)
POST /v2/batches	Start batch call/SMS

Decision guidance

When to use Prompt vs System Prompt

Use Prompt	Use System Prompt
Define the goal and specific instructions	Set tone, personality, formality
Tag tools and knowledge with @	Apply everywhere in agent and pathways
Describe order of operations	Describe how agent should sound
Handle specific conversation branches	Control communication style

When to attach knowledge vs tag it

Attach (checkbox on Knowledge page)	Tag (@ in prompt)
Make source available everywhere in agent	Tell agent where source matters in conversation
Source is always relevant	Source is contextually relevant at this point
Simpler for broad coverage	Better for focused retrieval hints
Both can be true; tagging adds context	Tagging alone does not attach

When to use Publish to Staging vs Force Promote

Publish to Staging	Force Promote
Normal workflow; runs evaluations	Skip evaluations; go straight to production
Staging tests before production	Emergency fix or override needed
Evaluations gate the move	Bypass recorded in audit log
Recommended for most changes	Use sparingly; unevaluated work goes live

When to use Webhook tool vs Webhook step

Webhook Tool	Webhook Step
Agent decides when to call it	Runs at guaranteed point in flow
Tagged into prompt with @	Placed inside pathway on canvas
Flexible, context-driven	Scripted, ordered sequence
Use for optional lookups	Use for required verification

Workflow

Build and test an agent

1. Create agent: Click New agent → Blank agent, give it a name and job
2. Write prompt: Describe what it does, the order of operations, how it handles edge cases
3. Add tools: Create webhook tools for APIs, tag them with @ in prompt (e.g., @check-calendar)
4. Add knowledge: Upload files or websites, attach them on Knowledge page, optionally tag with @ in prompt
5. Test manually: Use Manual tab on right side, talk to agent, watch debug logs
6. Add pathways: For complex flows, create Prompt, Pathway, or Authentication zone pathways with routing conditions
7. Configure settings: Set voice, language, memory, recording, metadata on Settings tab
8. Save: Work is auto-saved; explicit save happens on publish

Publish and promote to production

1. Publish to staging: Click Publish button (top right), choose version bump (patch/minor/major)
2. Wait for evaluations: If configured, checks run automatically; blocked publish leaves version on dev
3. Review staging: Switch environment selector to Staging, test if needed
4. Promote to production: Click Promote button, confirm the change
5. Verify: Check Environments page Activity log shows deployment, attach phone number if needed

Attach phone number and dispatch calls

1. Get number: Go to Dispatch → Phone numbers (All agents scope), activate free number or buy one
2. Attach to agent: Press Configure, set Agent in Assignment dropdown, save
3. Verify agent is promoted: Agent must be in production; if not, promote first
4. Test: Call the number or use Talk in browser from agent page
5. Run batch: Upload CSV with phone_number column, pick agent and script, review and send

Debug a failing call

1. Check production version: Environments page → Production row; if empty, agent is unpinned
2. Verify number is attached: Dispatch → Phone numbers, check Assignment column
3. Read transcript: Conversations page, open call, check Transcript and Detail tabs
4. Check tool failures: Look for tool calls in timeline, check Analytics for failure rate
5. Test retrieval: Knowledge → Source testing, ask the question the agent got wrong
6. Review logs: Click turn in timeline, open Testbed or Raw LLM context to see agent's input

Common gotchas

• Agent does not answer calls: Most common cause is agent not promoted to production. Publishing alone is not enough; must promote. Check Environments page.
• Tool never fires: Tool must be tagged in prompt with @. Building a tool does not attach it. Check Tool references section under prompt.
• Tool fires at wrong time: Description is what agent reads to decide when to use it. Rewrite description to say when to use it, not what endpoint does.
• Knowledge source not used: Source must be attached (checkbox on Knowledge page) AND saved. Tagging alone does not attach. Check both.
• Edited tool but agent uses old version: Tagging creates a copy. Edit from Tool references row, not from Tools page. Editing from Tools page changes library only.
• Variable extraction adds latency: Each variable costs response time. Extract only what you will use. Check Variables to extract section.
• Pathway never runs: Pathway must have routing condition set. Without one, agent has no reason to enter it. Click pathway row to set condition.
• Webhook tool times out: Increase Timeout (milliseconds, 1000-60000), make endpoint faster, or add Agent speech so caller hears something.
• Secret in body breaks on rename: Body references use {{secret.NAME}}, not ID. Renaming breaks it. Use header references instead (they support both).
• Staging number still runs production version: Only calls follow staging; texts run production. Staging numbers need all variables set on staging.
• Batch upload rejected: CSV must have column named exactly phone_number, numbers need country code (+1 format). Error names up to 3 bad rows.
• Evaluations block publish: Required evaluation failed. Version is saved on dev with no number. Fix what failed and publish again; nothing is lost.
• Environment variable unresolved: Variable set on dev but not on staging/production. Each environment needs its own value. Check Variables tab per environment.

Verification checklist

Before submitting work with an agent:

• Agent is saved (no unsaved changes indicator)
• Agent is promoted to production (check Environments page, Production row has version)
• Phone number is attached if needed (Dispatch → Phone numbers, Assignment column shows agent name)
• Tools are tagged in prompt (Tool references section is not empty if tools are needed)
• Knowledge sources are attached (Knowledge page, checkboxes are checked and saved)
• Manual test passes (talk to agent in browser, verify expected behavior)
• Evaluations pass if configured (Publish dialog shows no blocks, Checks card shows green)
• Transcripts are readable (open a test call, check Transcript tab for clarity)
• Tool calls succeed (Analytics tab shows low failure rate, or test tool directly)
• Knowledge retrieval works (Source testing tab, ask a question, check top chunk score)
• Batch CSV is valid (phone_number column exists, numbers have country codes, no duplicates)
• Staging number points to staging if testing (Channels page, number shows Staging environment)

Resources

Comprehensive page-by-page navigation: https://docs.bland.ai/llms.txt

Critical documentation pages:

• Build your first agent — Four-step onboarding walkthrough
• Agent builder — Complete reference for prompts, tools, knowledge, pathways, settings
• Dispatch — Phone numbers, batches, triggers, channels
• Environments — Publish, promote, rollback, staged release, variables
• Tools — Webhook, custom code, integration tools; secrets; tagging
• Knowledge — Sources, attachment, retrieval testing, gap management
• Conversations — Transcripts, call logs, analysis, debugging
• API v2 Overview — Programmatic agent creation and management

---

For additional documentation and navigation, see: https://docs.bland.ai/llms.txt