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

# Work with agents through MCP

> Inspect, create, edit, and validate agents through your connected assistant.

Start with [workspace verification](https://docs.agents.labs.bandwidth.com/mcp/workspaces.md#verify-workspace-access), then use these prompts.

## Work with agents

Try these prompts after verifying the connection:

| Task | Prompt |
| - | - |
| Read an agent | "List my agents, then show the current definition of the one I select. Do not change anything." |
| Inspect phone assignments | "List all registered phone numbers in this workspace and show which agent each one routes to, including inactive and unassigned numbers." |
| Find product guidance | "Search the Agent Builder docs for webhook payloads, then read the relevant page." |
| Plan an agent | "Use the voice prompting guide to propose an appointment assistant. Show me the prompt before creating it." |
| Edit a draft | "Read my selected prompt-based agent, propose a shorter greeting, and wait for approval before saving it." |
| Check readiness | "Validate my selected agent and explain any definition errors or readiness issues without changing it." |

For a simple agent, use `create_single_prompt_agent`. For a workflow with multiple steps or branches, use `create_workflow` or a template available to your account. Agent creation tools return a `workflow_id`; reuse it to read, edit, or validate that agent. Check the returned `created`, `saved`, or `updated` field before retrying a write. Repeating a successful create can make a duplicate.

`get_workflow` returns the current workflow source and its metadata together. Use `update_single_prompt_agent` to change a prompt-based agent's system prompt or greeting; fields you omit remain unchanged, and an empty greeting clears it. For a canvas workflow, send the complete edited source to `save_workflow`. These edit tools save a draft and leave the published definition unchanged.

Catalog tools return stable identifiers such as `tool_uuid`, `document_uuid`, and `credential_uuid`. Look up an item in its catalog before referencing it in a workflow instead of guessing an ID. Credential results contain metadata, not secret values. Create or change credentials in the Agent Builder UI. When editing a canvas workflow with masked credential values, keep the existing node ID and type so the saved secret can be retained; do not replace a masked value with a guessed secret. Creating an MCP tool can contact its remote server to discover the server's available tools.

## Review and publish

New agents start in **Draft** and do not receive external calls until you publish them from the UI. `lifecycle_status` describes the agent (`draft`, `active`, `paused`, or `archived`); `version_status` describes the selected definition (`draft` or `published`). A published definition does not by itself mean the agent is active.

Use `validate_workflow` as a preflight. It reports workflow-definition errors and a local model-configuration readiness check. It does not call a model provider or configured endpoint, place a test call, or publish the agent. URL-safety checks may resolve configured endpoint hostnames through DNS. Review provider settings and prompts, test the agent in the UI, and publish it there when it is ready.

Users with the Editor, Admin, or Owner role can create and edit agents. Only Admins and Owners can configure stored authentication credentials, custom headers, or preset values on reusable tools. Authoring tools return structured results: on failure, `created`, `saved`, or `updated` is `false`, with `error_code` and `error` fields explaining why. Permission and access failures may be returned as MCP tool errors. Check the result before retrying a write.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.