> ## Documentation Index > Fetch the complete documentation index at: https://docs.bland.ai/llms.txt > Use this file to discover all available pages before exploring further. # Norm plugin > Install norm@bland to build, migrate, validate, and test Bland Agents from your coding agent. The **Norm plugin** (`norm@bland`) is the recommended setup for building Bland Agents from your coding agent. It connects to your account through the [Bland MCP server](https://docs.bland.ai/integrations/mcp/overview.md) and supplies the skills and commands to build, migrate, validate, and test agents. One plugin, three layers: * **The hosted MCP server** at `api.bland.ai/v1/mcp` reads and writes against your account: agents, versions, simulations, call logs, analytics, and docs search. * **Skills** teach the agent how to work with Bland Agents authoring, runtime behavior, evaluations, call analysis, tools, knowledge, environments, channels, and launch workflows. * **The `/norm:*` commands** guide new builds and migrations using raw JSON agent snapshots. Deterministic builders and audits preserve source content, and a convergence loop checks the saved version against simulations. > [!NOTE] > > `norm@bland` is the plugin for Bland Agents. The separate `bland@bland` plugin covers v1 pathways, personas, and the file-based pathway workspace. Install both only if you work on both platforms. The `/bland:*` workspace commands are not part of Norm. Using VS Code, Windsurf, Gemini CLI, or a client the plugin does not support? Connect the server directly from the [MCP clients](https://docs.bland.ai/integrations/mcp/clients.md) page. ## Prerequisites * A Bland API key from [app.bland.ai/settings/api-keys](https://app.bland.ai/settings/api-keys), for the organization that owns your agents or migration source. Never paste it into the chat; configure it in your host as described below. * Node.js 18 or newer for the local builder, audits, and hooks. ## Install > [tab] Claude Code > > Inside a Claude Code session: > > ```text theme={null} > /plugin marketplace add CINTELLILABS/bland-plugins > /plugin install norm@bland > ``` > > Enter your API key in the install prompt. If it does not prompt, or you skipped it, configure the key outside the conversation: > > ```text theme={null} > /plugin configure norm@bland > ``` > > The host stores the key in your OS keychain. Restart the session, then type `/norm` to check that the build, migrate, validate, analytics, and simulate commands are available. Ask Norm to list your agents to verify the MCP connection and organization before making changes. > [tab] Claude Desktop > > Install `norm@bland` as for Claude Code. If the Desktop plugin browser does not prompt for the key, configure it in a session: > > ```text theme={null} > /plugin configure norm@bland > ``` > > Restart the app afterwards so the MCP connection picks it up. > [tab] Cursor > > Norm's Cursor manifest is in the [Norm package directory](https://github.com/CINTELLILABS/bland-plugins/tree/main/v2), but currently references a missing `mcp.json`. Do not assume the package configures the hosted connection. Until that packaging is fixed, use the [direct Cursor MCP setup](https://docs.bland.ai/integrations/mcp/clients/cursor.md) for server access. The root Bland plugin is the v1 package, not a substitute for Norm's Bland Agents skills. > [tab] Codex > > Norm includes a Codex manifest in the [Norm package directory](https://github.com/CINTELLILABS/bland-plugins/tree/main/v2). The repository's root Codex marketplace currently lists the v1 `bland` plugin, not Norm; do not select that entry for Bland Agents work. > > If your host cannot install the Norm package, clone `CINTELLILABS/bland-plugins`, tell your agent to follow `v2/commands` and `v2/skills`, and connect through the [direct Codex MCP setup](https://docs.bland.ai/integrations/mcp/clients/codex.md). This is the fallback used by Bland's migration setup prompt for other coding agents. > > Set `BLAND_API_KEY` in the environment that launches Codex. Enter it in your own terminal without echoing it or leaving it in shell history: > > ```bash theme={null} > printf 'Bland API key: ' > read -rs BLAND_API_KEY > printf '\n' > export BLAND_API_KEY > codex > ``` > > Codex reads the key from that environment only. For Codex Desktop, the key must be in the app's environment when it starts. > [!WARNING] > > Never paste your API key into the chat. Use the install prompt, the host's plugin settings, or your own terminal. To set, fix, or rotate the key on Claude Code, run `/plugin configure norm@bland`. > [!NOTE] > > On Codex, ask for the same work in plain language; it loads Norm's skills rather than Claude Code slash commands. The Stop-hook convergence gate runs only in Claude Code, after loop initialization. It checks the local audit and recorded save/simulation results, but can release on iteration limits, repeated failures, or a timeout. Those releases are incomplete, not passing verification. On other hosts, follow the audit, save, and simulation checks explicitly. ### Already using the Bland plugin? Install `norm@bland` alongside it and configure Norm's API key for the correct organization. Use `/norm:*` for Bland Agents and `/bland:*` only for v1 pathway work. Do not uninstall Norm or replace it with `bland@bland` for Bland Agents work. ## The flow, start to production 1. **Build it.** `/norm:build Build a Bland Agent for booking that collects name, callback number, and a time, then confirms it back.` Norm proposes the architecture, authors a JSON snapshot, audits it, and asks before saving an agent version. 2. **Give it tools and knowledge.** Ask Norm to connect your booking API and attach the information callers need. Review every integration's read and write behavior before testing. 3. **Prove it works.** `/norm:simulate Verify booking, unavailable times, and requests for a human.` Ask Norm to pin the saved candidate version explicitly and verify the run's recorded version. An agent ID alone does not pin a version: unpinned agent simulations use the latest development head. Norm inspects failure traces and repeats the full suite after changes. Untestable lanes are reported as uncovered. 4. **Define what to measure.** Ask for evaluation judges and dispositions for booking success, appointment time, and the reason a caller did not book. 5. **Ship safely.** Ask Norm to publish the verified version to staging, check the required evaluations and environment values, and promote only after you approve the exact candidate. Saving a version does not authorize changing live traffic. 6. **Watch and iterate.** Ask Norm to analyze calls and failures. Use `/norm:analytics` to build a Sankey or conversation cohort, then validate and simulate any agent changes before promoting them. ## Migrate an existing v1 pathway ```text theme={null} /norm:migrate Migrate my v1 pathway into a new Bland Agent named "Booking". Show me the proposed architecture, ask before the first version push, and finish with the full simulation suite and migration report. ``` Norm uses your v1 export as a read-only source, carries its content into a Bland Agents snapshot, audits parity, and verifies the new agent. Migration does not move phone numbers or change live v1 traffic. See [Migrate to agents](https://docs.bland.ai/platform/migrate-to-agents) for the full walkthrough. ## Edit an existing Bland Agent Ask Norm to fetch the agent and make a specific change while preserving stable IDs. It works with raw JSON snapshots rather than the v1 Markdown/YAML pathway workspace. Run `/norm:validate` on the updated snapshot, save a new version with approval, and use `/norm:simulate` to verify that exact version before promotion. ## Command reference | Command | What it does | | - | - | | `/norm:build ` | Design, author, audit, save, and verify a new Bland Agent. | | `/norm:migrate ` | Migrate a v1 pathway or persona into a Bland Agent: discover, architect, author, audit, save, and simulate. | | `/norm:validate ` | Audit a JSON snapshot for structure and routing problems, plus source parity when migrating. | | `/norm:analytics ` | Build or edit an agent's analytics Sankey, or create a conversation cohort. | | `/norm:simulate ` | Run and grade simulations, inspect failures, and verify a full suite on the exact saved version. | ## Skills On hosts that load the Norm package, skills are available when the conversation matches their description. Use the host's skill-loading behavior; having a manifest in the repository does not by itself verify a working installation. | Skill area | Use when | | - | - | | Authoring, snapshots, and runtime | Design new agents, author snapshots, and understand routing and execution. | | Migration | Carry v1 content into Bland Agents without losing prompts, rules, tools, or pinned versions. | | Maintenance | Update and debug existing agents with stable IDs and concurrency checks. | | Testing and evaluations | Run simulations, inspect traces, create judges, and verify exact versions. | | Lifecycle, environments, and launch | Manage versions, environment values, staging checks, promotion, and launch readiness. | | Analytics and call analysis | Build analytics views, find conversation cohorts, and investigate calls with evidence. | | Tools and knowledge | Create and test tools, manage secrets by reference, and attach knowledge. | | Dispositions | Define, test, and publish post-call outputs. | | Phone numbers, channels, and calls | Bind numbers, configure channels, and place calls with approval. | | Automations and issues | Configure triggers and track failures with evidence. | | API workspace | Find product references and work through the current Bland MCP/API schemas. | ## Safety * Confirm the organization through Norm's own MCP connection before the first write. Multiple Bland connections in one session can belong to different organizations. * Keep your host's tool-approval controls enabled and review writes, paid actions, calls, and promotions. These approval steps are host/operator responsibilities, not a guarantee that the server requires a human click. Approval to save a version is not approval to move live traffic. * Simulations can invoke real integrations. Keep write-side actions out of routine tests unless you explicitly authorize them, and report uncovered lanes rather than claiming they passed. * Review the saved staging evaluation policy. When it enables required evaluations, run and pass them for the candidate before promotion. Norm should not use `force` or weaken the policy to bypass a failure. * Your API key stays in the host's configuration or environment, not the chat. > [!NOTE] > > Advanced: configure `bland_api_url` in Claude's plugin settings to target a staging server. Codex's packaged manifest uses the production URL. For Cursor's direct MCP setup, set the server URL in your MCP configuration rather than relying on the incomplete plugin package. A keyless Claude install supports local builders and audits, but API operations still need a configured key or explicit approval to use a project-supplied Bland connection. ## Related > [card] [Bland MCP Server](https://docs.bland.ai/integrations/mcp/overview.md) > > The hosted MCP endpoint behind the plugin. > [card] [Tool reference](https://docs.bland.ai/integrations/mcp/tools.md) > > Every tool the server exposes. > [card] [Norm](https://docs.bland.ai/tutorials/norm.md) > > The in-app version of Norm in the Bland dashboard. > [card] [Agent builder](https://docs.bland.ai/agents/agent-builder.md) > > Build and edit Bland Agents with Norm. *** Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.