Work with agents
Try these prompts after verifying the connection:
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.