Agent Builder Tool

Agent Builder Tool creates and manages custom AI agents: lifecycle, composition (tools and workflows), context documents, and showcase chat previews.

Response field allowlist (read this first)

Responses use a strict allowlist. system_prompt and chat_model are writable but are never returned by any action, including fetch_existing. Keep your own copy of a system prompt if you need to read it back or edit it incrementally.

Actions

create_new

Create a private draft agent.

• name (required; omitting it returns AGENT_CREATE_NAME_REQUIRED)
• description, chat_model, context_document_ids
• remixed_from_agent_id, remixed_from_agent_name to create the draft as a remix of a source you can view
• When remixed_from_agent_id is supplied, the source composition is authoritative: accessible tools, workflows, Agent Context documents, a non-empty system prompt, and an available chat model are cloned. Caller-supplied chat_model and context_document_ids are ignored on that path.

update_existing

Update fields on an agent you own.

• agent_id (required)
• name, description, status (draft | active | archived), chat_model, system_prompt, context_document_ids
• Prefer the dedicated publish and archive actions over setting status directly

fetch_existing

List your agents (most recently updated first) or fetch one by id or slug.

• agent_id to fetch one; query, limit (1-100), skip to list
• Unreadable or missing agents return AGENT_FETCH_NOT_FOUND (existence is masked)

search_public

Browse active public agents. query, limit, skip. Only agents that are active AND public AND unarchived appear here.

publish

agent_id. Moves a draft to active. The first publish stamps published_at and promotes draft_slug to the public slug (clearing draft_slug); later publishes keep both. Publishing does not make an agent public: visibility stays private and the agent will not appear in search_public. Public visibility is driven by the admin-only is_template flag.

archive

agent_id, optional forward_to.

• forward_to must be an internal path starting with / and free of ... Anything else, including an absolute URL, is silently ignored: the agent is archived and no redirects are written (redirects_written: 0).
• If a well-formed path fails deeper validation (pointing at the agent's own URL, or at a path that is already redirected) the call returns AGENT_ARCHIVE_SEO_REDIRECT_FAILED and the agent is left unarchived so it can be retried safely.
• On success the response reports redirects_written (one per canonical path: the slug path and the id path).

remix

agent_id, optional name. Creates a new private draft from any agent you can view and leaves the source unchanged.

• Copies every source item the new owner can access: products, workflows, Agent Context documents, a non-empty system prompt, and a still-available chat model.
• Missing, inactive, inaccessible, or unavailable items are omitted without failing an otherwise usable clone and are reported in skipped[] with kind, id, and reason.
• Showcase examples, template/publication/archive state, source URLs, and the source remix count are not copied.
• Sets remixed_from_* and original_creator_* attribution and increments the source's remix_count.

add_product / remove_product

agent_id, product_id. Attaches or detaches a tool. File Manager is appended automatically when any attached tool, or any tool inside an attached workflow, needs file storage; the response reports file_manager_added. Auto-attach is add-only, so File Manager stays attached after you remove the product that pulled it in. Unknown, inactive, or inaccessible products return AGENT_COMPOSITION_PRODUCT_NOT_FOUND.

add_workflow / remove_workflow

agent_id, workflow_id. Same automatic file storage behavior applies.

attach_context / detach_context

agent_id, context_document_id. Maximum 10 documents per agent. A malformed id returns AGENT_CONTEXT_INVALID_ID. Private context documents are rejected on public active agents.

add_showcase_example / remove_showcase_example

agent_id plus showcase_example (object) or showcase_example_id (string). Only one example may be featured; adding a featured example unfeatures the previous one. Duplicate ids return AGENT_SHOWCASE_DUPLICATE_ID; malformed examples return AGENT_SHOWCASE_INVALID_ASSET.

get_instructions

Returns this reference.

Showcase example shape

2 to 10 messages, at least one user and one assistant. Roles do not need to alternate. Each message needs id, role, timestamp (ISO 8601), and a non empty parts array. Use durable public URLs or a file_id for any media; unsigned private storage URLs are rejected.

Examples

{"action":"create_new","name":"Deal Desk","description":"Sales follow-up agent for the Pipedrive pipeline."}

{"action":"add_product","agent_id":"<agent_id>","product_id":"<product_id>"}

{"action":"update_existing","agent_id":"<agent_id>","system_prompt":"Work only from records in the CRM. Never invent commitments. Every email is a draft for review."}

{"action":"publish","agent_id":"<agent_id>"}

{"action":"archive","agent_id":"<agent_id>","forward_to":"/agents/replacement-agent"}

Response

Actions return the affected agent payload (id, name, slug, draft_slug, status, visibility, products, workflows, context_document_ids, showcase_examples, plus computed categories and industry_tags derived from the attached products). Successful remix responses also include skipped[] (possibly empty). Errors return a stable AGENT_* error code with a usable message.