Custom agents API

Custom agents have a mutable draft and immutable published versions. Use the VegaFlow API base /api/v1/vegaflow/orgs/{org_id}/workspaces/{workspace_id}/agents.

Author and publish

POST /agents takes name, optional display_name, description and icon, and an initial draft definition using vega.agent/v1.1. Names begin with a lowercase letter and contain 1–64 lowercase letters, digits, underscores or hyphens. Names are unique within a workspace; vega_ai is reserved.

GET /agents supports search, a keyset cursor and limit (1–100). It returns agents the caller can read. List items and GET /agents/{id} return metadata, the current version ID and number, a draft summary (resource version, digest, updater and time), and effective permissions. The full definition comes from draft GET. PATCH /agents/{id} changes display metadata in the draft.

Read the draft at GET /agents/{id}/draft. Replace it with PUT /agents/{id}/draft, sending the returned resource version in If-Match. A stale version returns 412. Drafts may be incomplete; POST /agents/{id}/draft/validate returns errors with paths.

Publish with POST /agents/{id}/versions, an If-Match draft resource version and optional notes. Publication checks the definition and the publisher's authority. Named connections must be usable by the publisher and allow the granted effects through ai_access. Actions must exist on their connector; MCP tools must be on the reviewed allow-list. Skills and model profiles must be available. The running user's permissions are checked again at call time.

Versions have sequential numbers, a digest, publisher, publication time and notes. Publishing an unchanged digest returns the existing version. List versions at GET /agents/{id}/versions, read one at GET /agents/{id}/versions/{version_id}, and select an older release with PUT /agents/{id}/current-version and {"version_id":"uuid"}.

GET /agents/catalog returns grantable platform tools, workspace connections and connector actions, reviewed MCP tools, enabled skills and model-profile names. Custom definitions name workspace connection IDs and MCP tools explicitly.

Permissions

Grants apply to one agent or to all agents in a workspace. read allows agent metadata, definitions and versions; use allows published chat and includes visibility; edit allows draft changes and test chat; publish allows publishing, selecting the current release, disabling and enabling. admin includes all agent capabilities, deletion and grant management. A workspace-level edit grant permits creation. The creator receives admin on the new agent.

Use GET, POST and DELETE /agents/{id}/permissions to list, grant and revoke user, group and role grants using the standard permissions request schema. Unknown permissions and service-principal entries return 422 with field paths. Built-in Vega AI keeps its separate permissions.

Chat and test drafts

POST /agents/{id}/conversations accepts version (a published version UUID, "draft", or omitted for the current version) and optional approval_mode. Published chat requires use; selecting an older version additionally requires edit or publish. Draft chat requires edit and a valid draft. Each conversation pins its definition. Later draft edits and current-version changes do not alter it. After a rollback or other current-version change, a use-only owner can still read the pinned transcript, but ask and steer return 409 with code AGENT_VERSION_CHANGED and message "This agent's version changed; start a new conversation." Owners with use plus edit or publish may continue. Draft snapshots are excluded from published version lists.

The question and event schemas match Vega AI chat:

• GET /agents/{id}/conversations/{conversation_id}
• GET/POST /agents/{id}/conversations/{conversation_id}/questions
• GET /agents/{id}/questions/{question_id}
• POST /agents/{id}/questions/{question_id}/cancel
• POST /agents/{id}/questions/{question_id}/messages for steering
• GET /agents/{id}/questions/{question_id}/events: SSE or JSON replay with Accept: application/json; supports cursor and Last-Event-ID

Asking requires a UUID Idempotency-Key. The owner still needs use for published chats or edit for drafts to read their history. Agent admins can review another owner's transcript, questions, events and inline approvals, with connection prompts hidden and personal account identities redacted. That reviewer view is read-only. Other users receive 404. Only the owner can ask, steer, cancel or decide. Approvals also appear in the workspace inbox. Event requests recheck permissions before waiting; revocation takes effect on the next request after the current wait window, at most 25 seconds. Custom conversation listing and forking are not available yet.

DESTRUCTIVE tools require explicit connection and action/tool names, ai_access=allowed_destructive, and human approval on every call, including auto mode. allowed covers only READ, DRAFT and WRITE. Destructive ceilings cannot widen non-destructive actions or wildcard grants. Approved destructive executions are audited with their effect. Built-in Vega AI grants no destructive tools. Custom agents use their authored instructions; personal and workspace Vega AI instructions apply only to the built-in agent.

Disable and delete

POST /agents/{id}/disable refuses new runs; POST /agents/{id}/enable allows them again. DELETE /agents/{id} returns 409 while runs are active. Deletion hides the agent from lists, prevents new runs and frees its name for reuse. Existing versions and retained history remain readable to authorized callers under the normal retention policy.