New VDF AI Enterprise is now available on AWS Marketplace
API Reference

Agents

An agent pairs a model with a system prompt, a set of tools, and optional skills. Agents come in two kinds: system agents, curated for the deployment and visible to everyone, and agents you create, which are private to you. The two share one namespace and one object shape.

The registry endpoints below address agents you create by their id. Listing and running also accept system agents. All calls are scoped to the caller: you see and can run system agents plus your own (and any shared with you), and only the owner of an agent can update or delete it.

Running an agent is a single synchronous call to Run an agent; everything else manages the registry. Agents can be scoped to workspaces, which determine the tools and knowledge sources available to a run.

Endpoints 11

Paths are relative to /agent-hub-api

The agent object

The configuration of a single agent.

Attributes

  • id nullable string

    Unique identifier, a UUID. System agents that have not been persisted may report null.

  • name string

    Display name. For agents you create it matches ^[a-zA-Z0-9_]+$ and is unique within your own agents.

  • description nullable string

    Free-text summary of what the agent does.

  • version string

    Author-assigned version string, such as 1.0.

  • owner_user_id nullable integer

    The user who owns the agent, or null for a system agent.

  • domain_id nullable string

    The domain the agent belongs to, or null.

  • domain_slug nullable string

    Slug of the agent's domain.

  • domain_name nullable string

    Display name of the agent's domain.

  • category nullable string

    Optional grouping label.

  • sub_category nullable string

    Optional secondary grouping label.

  • model_name nullable string

    Identifier of the model the agent runs on, from your model catalogue.

  • system_prompt nullable string

    The instructions prepended to every run.

  • competencies array of strings

    Free-text capability tags.

  • skills array of strings

    Deprecated alias for competencies, carrying the same values. Read competencies instead.

  • skills_config array of objects

    Skills bound to the agent.

    Show child attributes Hide child attributes
    • name string

      The skill name.

    • version nullable string

      Pinned skill version, or null for the current one.

  • output_format string

    Expected output shape.

    Possible values
    • text
    • json
    • widget
  • tools_config array of objects

    The tools available to the agent, each with a name and a parameter schema. See Tools.

  • model_parameters object

    Generation parameters such as temperature, max_tokens, top_p, frequency_penalty, and presence_penalty.

  • is_user_created boolean

    true for an agent you created, false for a system agent.

  • workspace_ids array of strings

    Identifiers of the workspaces the agent belongs to.

  • workspace_slugs array of strings

    Slugs of the workspaces the agent belongs to.

  • skill_tool_gaps object

    For each bound skill, the tools it declares as allowed that the agent does not currently grant. An empty object means every skill has the tools it expects.

  • created_at string

    Creation timestamp, ISO 8601.

  • updated_at string

    Last-update timestamp, ISO 8601.

The agent object 
{
  "id": "3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11",
  "name": "quarterly_report_writer",
  "description": "Drafts quarterly business reports from supplied figures.",
  "version": "1.0",
  "owner_user_id": 42,
  "domain_id": "b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90",
  "domain_slug": "communication",
  "domain_name": "Communication",
  "category": "communication",
  "sub_category": "reporting",
  "model_name": "llama-3.3-70b-instruct",
  "system_prompt": "You are a concise business report writer. Use the figures provided and do not invent numbers.",
  "competencies": [
    "summarisation",
    "business writing"
  ],
  "skills": [
    "summarisation",
    "business writing"
  ],
  "skills_config": [
    {
      "name": "report-formatting",
      "version": null
    }
  ],
  "output_format": "text",
  "tools_config": [
    {
      "name": "web_search",
      "type": "mcp",
      "description": "Search the web.",
      "parameters_schema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          }
        },
        "required": [
          "query"
        ]
      }
    }
  ],
  "model_parameters": {
    "temperature": 0.7,
    "max_tokens": 2000
  },
  "is_user_created": true,
  "workspace_ids": [
    "a2c4e6f8-1234-4abc-9def-0123456789ab"
  ],
  "workspace_slugs": [
    "finance"
  ],
  "skill_tool_gaps": {},
  "created_at": "2026-09-01T09:30:00",
  "updated_at": "2026-09-01T09:30:00"
}

List agents

GET /agent-hub-api/api/agent/list

Returns the agents the caller can run.

Returns system agents plus the agents you own (and any shared with you). Each entry is a compact summary rather than the full agent object.

Use source to choose where agents are drawn from. Filter to a single workspace with workspace_slug or workspace_id, or with the X-Workspace-Slug header; workspaces shared with your company are included. Send an empty X-Workspace-Slug header to opt out of the active-workspace filter and list every agent.

Authentication
Bearer token How it works

Headers

  • X-Workspace-Slug string

    Active workspace to filter by. An empty value disables workspace filtering.

Query parameters

  • source string

    Where to list agents from: yaml for system agents, db for stored agents, or all for both.

    Defaults to yaml.

    Possible values
    • yaml
    • db
    • all
  • user_only boolean

    When source is db, restrict the result to agents you created.

    Defaults to false.

  • domain_id string

    Return only agents in this domain.

  • workspace_slug string

    Return only agents belonging to the workspace with this slug.

  • workspace_id string

    Return only agents belonging to the workspace with this identifier.

Returns

Returns an object with an agents array of agent summaries.

Request 
curl "$VDF_BASE_URL/agent-hub-api/api/agent/list?source=all" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "ok": true,
  "user_id": 42,
  "agents": [
    {
      "id": "3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11",
      "name": "quarterly_report_writer",
      "description": "Drafts quarterly business reports from supplied figures.",
      "domain_id": "b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90",
      "domain_slug": "communication",
      "domain_name": "Communication",
      "category": "communication",
      "sub_category": "reporting",
      "model": "llama-3.3-70b-instruct",
      "cached": false,
      "source": "db",
      "is_user_created": true,
      "owner_user_id": 42
    }
  ]
}

Create an agent

POST /agent-hub-api/api/agent/db

Creates an agent that you own.

Creates an agent owned by the caller. name and model_name are required; the model must exist in your catalogue.

Tool references may be tool names or objects with a name; each is resolved against the tool catalogue and rejected if unknown. Skill references are validated against the skills visible to you. If you supply one or more workspaces, the agent is added to them, and the domain (when given) must be mapped to each of those workspaces.

Authentication
Bearer token How it works

Headers

  • X-Workspace-Slug string

    Workspace to attach the agent to when no workspace_ids or workspace_slugs are supplied.

Body parameters application/json

  • name string Required

    Agent name. Must match ^[a-zA-Z0-9_]+$ and be unique among your agents.

  • model_name string Required

    Identifier of a model in your catalogue.

  • description string

    Free-text summary.

  • version string

    Version string.

    Defaults to 1.0.

  • system_prompt string

    Instructions prepended to every run.

  • domain_id string

    Domain to file the agent under.

  • category string

    Optional grouping label.

  • sub_category string

    Optional secondary grouping label.

  • competencies array of strings

    Free-text capability tags.

  • output_format string

    Expected output shape.

    Defaults to text.

    Possible values
    • text
    • json
    • widget
  • tools array of strings

    Tool references, given as names or objects with a name. Each must resolve to a known tool.

  • skills_config array of objects

    Skills to bind, as names or {name, version} objects.

  • model_parameters object

    Generation parameters such as temperature and max_tokens.

  • workspace_ids array of strings

    Workspaces to attach the agent to, by identifier.

  • workspace_slugs array of strings

    Workspaces to attach the agent to, by slug.

Returns

Returns the created agent object under data.

Errors

  • 400 A required field is missing, or tool, skill, or workspace validation failed.
  • 401 The request carries no usable user identity.
  • 503 Tool references could not be resolved because the tool service was unavailable.
Request 
curl -X POST "$VDF_BASE_URL/agent-hub-api/api/agent/db" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quarterly_report_writer",
    "model_name": "llama-3.3-70b-instruct",
    "description": "Drafts quarterly business reports from supplied figures.",
    "system_prompt": "You are a concise business report writer. Use the figures provided and do not invent numbers.",
    "competencies": [
      "summarisation",
      "business writing"
    ],
    "output_format": "text",
    "tools": [
      "web_search"
    ],
    "model_parameters": {
      "temperature": 0.7,
      "max_tokens": 2000
    },
    "workspace_slugs": [
      "finance"
    ]
  }'
Response 201 
{
  "success": true,
  "message": "Agent 'quarterly_report_writer' created in database",
  "data": {
    "id": "3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11",
    "name": "quarterly_report_writer",
    "description": "Drafts quarterly business reports from supplied figures.",
    "version": "1.0",
    "owner_user_id": 42,
    "model_name": "llama-3.3-70b-instruct",
    "output_format": "text",
    "competencies": [
      "summarisation",
      "business writing"
    ],
    "tools_config": [
      {
        "name": "web_search",
        "type": "mcp",
        "description": "Search the web.",
        "parameters_schema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string"
            }
          },
          "required": [
            "query"
          ]
        }
      }
    ],
    "model_parameters": {
      "temperature": 0.7,
      "max_tokens": 2000
    },
    "is_user_created": true,
    "workspace_ids": [
      "a2c4e6f8-1234-4abc-9def-0123456789ab"
    ],
    "workspace_slugs": [
      "finance"
    ],
    "skill_tool_gaps": {},
    "created_at": "2026-09-01T09:30:00",
    "updated_at": "2026-09-01T09:30:00"
  }
}

Retrieve an agent

GET /agent-hub-api/api/agent/db/id/{agent_id}

Retrieves a single agent by its identifier.

Returns the full agent object. System agents are visible to everyone; an agent you created is visible only to you. An agent that is not visible to the caller returns 404.

Authentication
Bearer token How it works

Path parameters

  • agent_id string Required

    The agent identifier (UUID).

Returns

Returns the agent object under data.

Errors

  • 401 The request carries no usable user identity.
  • 404 No agent with this identifier is visible to the caller.
Request 
curl "$VDF_BASE_URL/agent-hub-api/api/agent/db/id/3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": {
    "id": "3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11",
    "name": "quarterly_report_writer",
    "description": "Drafts quarterly business reports from supplied figures.",
    "version": "1.0",
    "owner_user_id": 42,
    "domain_id": "b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90",
    "domain_slug": "communication",
    "model_name": "llama-3.3-70b-instruct",
    "system_prompt": "You are a concise business report writer. Use the figures provided and do not invent numbers.",
    "competencies": [
      "summarisation",
      "business writing"
    ],
    "skills_config": [
      {
        "name": "report-formatting",
        "version": null
      }
    ],
    "output_format": "text",
    "tools_config": [
      {
        "name": "web_search",
        "type": "mcp",
        "description": "Search the web.",
        "parameters_schema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string"
            }
          },
          "required": [
            "query"
          ]
        }
      }
    ],
    "model_parameters": {
      "temperature": 0.7,
      "max_tokens": 2000
    },
    "is_user_created": true,
    "workspace_ids": [
      "a2c4e6f8-1234-4abc-9def-0123456789ab"
    ],
    "workspace_slugs": [
      "finance"
    ],
    "skill_tool_gaps": {},
    "created_at": "2026-09-01T09:30:00",
    "updated_at": "2026-09-01T09:30:00"
  }
}

Update an agent

PUT /agent-hub-api/api/agent/db/id/{agent_id}

Updates an agent you own.

Applies a partial update: send only the fields you want to change. Only an agent you created can be updated through this endpoint, and only by its owner; anything else returns 404.

Supplying workspace_ids or workspace_slugs replaces the agent's workspace membership, and at least one workspace must remain. Tool references are re-resolved against the catalogue on every update.

Authentication
Bearer token How it works

Path parameters

  • agent_id string Required

    The agent identifier (UUID).

Body parameters application/json

  • description string

    Free-text summary.

  • model_name string

    Identifier of a model in your catalogue.

  • system_prompt string

    Instructions prepended to every run.

  • domain_id string

    Domain to file the agent under.

  • category string

    Optional grouping label.

  • sub_category string

    Optional secondary grouping label.

  • competencies array of strings

    Free-text capability tags.

  • skills_config array of objects

    Skills to bind, as names or {name, version} objects.

  • output_format string

    Expected output shape.

    Possible values
    • text
    • json
    • widget
  • version string

    Version string.

  • tools array of strings

    Tool references, replacing the agent's tools.

  • model_parameters object

    Generation parameters.

  • workspace_ids array of strings

    Replacement workspace membership, by identifier.

  • workspace_slugs array of strings

    Replacement workspace membership, by slug.

Returns

Returns the updated agent object under data.

Errors

  • 400 The body is empty, tool or workspace validation failed, or the agent cannot be updated through this endpoint.
  • 401 The request carries no usable user identity.
  • 404 No agent with this identifier is owned by the caller.
  • 503 Tool references could not be resolved because the tool service was unavailable.
Request 
curl -X PUT "$VDF_BASE_URL/agent-hub-api/api/agent/db/id/3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Drafts quarterly and annual business reports.",
    "model_parameters": {
      "temperature": 0.5,
      "max_tokens": 3000
    }
  }'
Response 200 
{
  "success": true,
  "data": {
    "id": "3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11",
    "name": "quarterly_report_writer",
    "description": "Drafts quarterly and annual business reports.",
    "version": "1.0",
    "owner_user_id": 42,
    "model_name": "llama-3.3-70b-instruct",
    "output_format": "text",
    "competencies": [
      "summarisation",
      "business writing"
    ],
    "tools_config": [
      {
        "name": "web_search",
        "type": "mcp",
        "description": "Search the web.",
        "parameters_schema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string"
            }
          },
          "required": [
            "query"
          ]
        }
      }
    ],
    "model_parameters": {
      "temperature": 0.5,
      "max_tokens": 3000
    },
    "is_user_created": true,
    "workspace_ids": [
      "a2c4e6f8-1234-4abc-9def-0123456789ab"
    ],
    "workspace_slugs": [
      "finance"
    ],
    "skill_tool_gaps": {},
    "created_at": "2026-09-01T09:30:00",
    "updated_at": "2026-09-02T11:15:00"
  }
}

Delete an agent

DEL /agent-hub-api/api/agent/db/id/{agent_id}

Permanently deletes an agent you created. Only the owner may delete it; an identifier that is not yours returns 404, and a system agent cannot be deleted through this endpoint.

Authentication
Bearer token How it works

Path parameters

  • agent_id string Required

    The agent identifier (UUID).

Returns

Returns success: true and a confirmation message once the agent is deleted.

Errors

  • 400 The agent cannot be deleted through this endpoint.
  • 401 The request carries no usable user identity.
  • 404 No agent with this identifier is owned by the caller.
Request 
curl -X DELETE "$VDF_BASE_URL/agent-hub-api/api/agent/db/id/3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "message": "Agent deleted"
}

Run an agent

POST /agent-hub-api/api/agent/execute

Runs a named agent against a prompt and returns its output, the model that produced it, any tool it called, and the token usage recorded for your licence. Identify the agent by agent_name (system or your own) or by agent_id (an agent you own); one of the two is required, along with prompt.

Before the model is called, the agent's tools are filtered to those you are entitled to use. To run inside a workspace, pass context.workspace_id or context.workspace_slug, or the X-Workspace-Slug header. The workspace is resolved on the server against your visibility and its tools, knowledge sources, and callable templates are applied to the run; any workspace fields you place in context are replaced by the server-resolved values.

This is a synchronous call: the response arrives when the agent has finished, which can take several minutes.

Long-running request. This call can take several minutes. Allow a generous read timeout — see Long-running requests.
Authentication
Bearer token How it works

Headers

  • X-Workspace-Slug string

    Workspace to run inside, used when context carries no workspace.

Body parameters application/json

  • agent_name string

    Name of the agent to run. Required unless agent_id is given.

  • agent_id string

    Identifier of an agent you own. Required unless agent_name is given.

  • prompt string Required

    The instruction or question for the agent.

  • context object

    Optional run context.

    Show child parameters Hide child parameters
    • workspace_id string

      Workspace to scope the run to, by identifier.

    • workspace_slug string

      Workspace to scope the run to, by slug.

    • session_id string

      Existing conversation to continue. A new session is created when omitted.

    • client_id string

      Identifier of the calling client application, recorded with the run.

Returns

Returns the run result, including the generated output and token usage.

Errors

  • 400 prompt is missing, or neither agent_name nor agent_id was given.
  • 403 The agent is not permitted for the calling application.
  • 404 No agent matching the request is visible to the caller.
  • 500 The run failed while calling the model or a tool.
Request 
curl -X POST "$VDF_BASE_URL/agent-hub-api/api/agent/execute" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "quarterly_report_writer",
    "prompt": "Summarise Q3: revenue 4.2M, up 12% QoQ; churn down to 1.8%.",
    "context": {
      "workspace_slug": "finance"
    }
  }'
Response 200 
{
  "success": true,
  "agent": "quarterly_report_writer",
  "model": "llama-3.3-70b-instruct",
  "output": "Q3 revenue reached 4.2M, up 12% quarter over quarter, while churn fell to 1.8%...",
  "tool": null,
  "tool_result": null,
  "usage": {
    "input": 210,
    "output": 180,
    "total": 390
  },
  "session_id": "d5b9f1a2-3c4e-4f6a-8b0c-1e2d3f4a5b6c",
  "execution_id": "e1f2a3b4-5c6d-4e7f-8a9b-0c1d2e3f4a5b"
}

Generate a system prompt

POST /agent-hub-api/api/agent/generate-system-prompt

Drafts a system prompt from a description of the agent.

Generates a structured system prompt from an agent's details, to use as a starting point when creating or editing an agent. name, description, and model_name are required. Tools may be given as names or as objects with a name and description. This calls a model and requires your deployment's model provider to be configured.

Authentication
Bearer token How it works

Body parameters application/json

  • name string Required

    The agent's name.

  • description string Required

    What the agent should do.

  • model_name string Required

    Identifier of the model the agent will use.

  • version string

    Version string.

    Defaults to 1.0.

  • competencies array of strings

    Capability tags to reflect in the prompt.

  • output_format string

    Output shape to reflect in the prompt.

    Defaults to text.

    Possible values
    • text
    • json
    • widget
  • tools array of strings

    Tool references, as names or {name, description} objects.

  • model_parameters object

    Generation parameters to mention in the prompt.

Returns

Returns the generated prompt as system_prompt.

Errors

  • 400 A required field is missing, or the model provider is not configured.
  • 500 The prompt could not be generated.
Request 
curl -X POST "$VDF_BASE_URL/agent-hub-api/api/agent/generate-system-prompt" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quarterly_report_writer",
    "description": "Drafts quarterly business reports from supplied figures.",
    "model_name": "llama-3.3-70b-instruct",
    "competencies": [
      "summarisation",
      "business writing"
    ],
    "output_format": "text",
    "tools": [
      "web_search"
    ]
  }'
Response 200 
{
  "success": true,
  "system_prompt": "Role: You are a concise business report writer.\nGoals:\n- Turn supplied figures into a clear quarterly report.\n..."
}

Draft an agent conversationally

POST /agent-hub-api/api/agent/create-with-llm/chat

Advances an assisted, chat-driven agent draft one turn.

Takes the conversation so far and the current draft and returns an assistant reply plus an updated draft, so an agent can be assembled through dialogue. The model may only choose from the domains, models, tools, and workspaces available to you. When missing_fields is empty and there are no validation errors, ready_to_create is true and the draft can be sent to Create an agent from a draft.

Authentication
Bearer token How it works

Headers

  • X-Workspace-Slug string

    Active workspace used to seed the draft's workspace when none is supplied in context.

Body parameters application/json

  • messages array of objects Required

    The conversation so far. A non-empty list of {role, content} items where role is user or assistant.

    Show child parameters Hide child parameters
    • role string

      user or assistant.

      Possible values
      • user
      • assistant
    • content string

      Message text.

  • draft object

    The current agent draft to refine.

  • context object

    Optional workspace seed.

    Show child parameters Hide child parameters
    • workspace_ids array of strings

      Workspaces to associate the draft with, by identifier.

    • workspace_slugs array of strings

      Workspaces to associate the draft with, by slug.

Returns

Returns the assistant reply, the merged draft, and readiness information.

Errors

  • 400 messages is missing or not a non-empty list of valid {role, content} items.
  • 401 The request carries no usable user identity.
  • 500 The assisted draft could not be generated.
Request 
curl -X POST "$VDF_BASE_URL/agent-hub-api/api/agent/create-with-llm/chat" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "I want an agent that drafts quarterly reports."
      }
    ],
    "draft": {}
  }'
Response 200 
{
  "success": true,
  "assistant_message": "Which model should it use, and should it be able to search the web?",
  "draft": {
    "name": "quarterly_report_writer",
    "description": "Drafts quarterly business reports.",
    "output_format": "text",
    "competencies": [
      "business writing"
    ]
  },
  "missing_fields": [
    "model_name",
    "domain_id",
    "version"
  ],
  "ready_to_create": false
}

Create an agent from a draft

POST /agent-hub-api/api/agent/create-with-llm/confirm

Creates an agent from a completed assisted draft.

Validates a completed draft and creates the agent you own. A missing system_prompt is generated automatically from the draft. Tools and skills are resolved and validated, workspaces are attached, and the chosen domain must be mapped to each attached workspace.

Authentication
Bearer token How it works

Headers

  • X-Workspace-Slug string

    Workspace to attach the agent to when the draft names none.

Body parameters application/json

  • draft object Required

    The completed draft, carrying at least the required fields (name, description, version, domain_id, model_name, output_format, competencies).

  • messages array of objects

    The originating conversation, for context.

  • workspace_slugs array of strings

    Workspaces to attach the agent to, by slug.

Returns

Returns the created agent object under data.

Errors

  • 400 The draft failed validation, or tool, workspace, or domain checks failed.
  • 401 The request carries no usable user identity.
  • 503 Tool references could not be resolved because the tool service was unavailable.
  • 500 The agent could not be created.
Request 
curl -X POST "$VDF_BASE_URL/agent-hub-api/api/agent/create-with-llm/confirm" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "I want an agent that drafts quarterly reports."
      }
    ],
    "draft": {
      "name": "quarterly_report_writer",
      "description": "Drafts quarterly business reports from supplied figures.",
      "version": "1.0",
      "domain_id": "b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90",
      "model_name": "llama-3.3-70b-instruct",
      "output_format": "text",
      "competencies": [
        "business writing"
      ],
      "tools": [
        "web_search"
      ]
    }
  }'
Response 201 
{
  "success": true,
  "message": "Agent 'quarterly_report_writer' created in database",
  "data": {
    "id": "3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11",
    "name": "quarterly_report_writer",
    "description": "Drafts quarterly business reports from supplied figures.",
    "version": "1.0",
    "owner_user_id": 42,
    "domain_id": "b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90",
    "model_name": "llama-3.3-70b-instruct",
    "output_format": "text",
    "competencies": [
      "business writing"
    ],
    "tools_config": [
      {
        "name": "web_search",
        "type": "mcp",
        "description": "Search the web.",
        "parameters_schema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string"
            }
          },
          "required": [
            "query"
          ]
        }
      }
    ],
    "model_parameters": {
      "temperature": 0.7,
      "max_tokens": 2000,
      "top_p": 0.95,
      "frequency_penalty": 0.2,
      "presence_penalty": 0.1
    },
    "is_user_created": true,
    "workspace_ids": [
      "a2c4e6f8-1234-4abc-9def-0123456789ab"
    ],
    "workspace_slugs": [
      "finance"
    ],
    "skill_tool_gaps": {},
    "created_at": "2026-09-01T09:30:00",
    "updated_at": "2026-09-01T09:30:00"
  }
}

Manage an agent by name Deprecated

GET /agent-hub-api/api/agent/db/{agent_name}

Also available as PUT /agent-hub-api/api/agent/db/{agent_name} DEL /agent-hub-api/api/agent/db/{agent_name}

Retired: name-based access to a stored agent is no longer supported.

This path is retired. Because agents you create are addressed by id (names are not unique across users), the GET, PUT, and DELETE methods on this path all return 400 with a message directing you to the identifier-based endpoints. Use Retrieve an agent, Update an agent, and Delete an agent instead.

Deprecated. Use the identifier-based endpoints: Retrieve an agent, Update an agent, and Delete an agent.
Authentication
Bearer token How it works

Path parameters

  • agent_name string Required

    Ignored; the request is rejected whatever value is given.

Returns

Always returns 400 directing you to the identifier-based endpoints.

Errors

  • 400 Always returned: name-based access is not supported. Use the identifier-based endpoints.
Request 
curl "$VDF_BASE_URL/agent-hub-api/api/agent/db/quarterly_report_writer" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 400 
{
  "success": false,
  "error": "Name-based DB agent lookup is not supported. Use the identifier-based endpoint instead."
}

Retrieve a system agent by name Deprecated

GET /agent-hub-api/api/agent/info/{agent_name}

Returns the details of a system agent identified by name. It resolves only system agents (the curated agents visible to everyone), so a name that is not a system agent returns 404. This is a legacy view retained for compatibility; retrieve any agent by its identifier with Retrieve an agent instead.

Deprecated. Use Retrieve an agent, which returns any agent by its identifier.
Authentication
Bearer token How it works

Path parameters

  • agent_name string Required

    Name of the system agent to look up.

Query parameters

  • source string

    Where to read the agent from: yaml for the curated definitions, or db/hybrid for the stored registry when it is enabled.

    Defaults to yaml.

    Possible values
    • yaml
    • db
    • hybrid

Returns

Returns the system agent's details.

Errors

  • 404 No system agent with this name exists.
  • 500 The agent details could not be read.
Request 
curl "$VDF_BASE_URL/agent-hub-api/api/agent/info/simple_assistant" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "name": "Simple Assistant",
  "description": "A versatile general-purpose assistant.",
  "version": "1.1",
  "domain_id": "b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90",
  "domain_slug": "general",
  "domain_name": "General",
  "category": "executive",
  "sub_category": "general",
  "model": {
    "name": "llama-3.3-70b-instruct"
  },
  "tools": [
    {
      "name": "web_search",
      "description": "Search the web."
    }
  ]
}