---
title: "Create Agent"
method: POST
path: "/v1/agent/create"
tags: ["agent"]
---

# Create Agent

`POST /v1/agent/create`

## Request

- Base URL: `https://api.vlm.run` (the document declares no server; this is the origin it was published from)
- URL: `https://api.vlm.run/v1/agent/create`
- Auth: HTTP bearer

## Request body

- AgentCreationRequest: Request to create an agent.
  - `config` AgentCreationConfig: Configuration for the agent creation request.
    - `prompt` string, nullable: The prompt to guide the creation of the agent.
    - `json_schema` object, nullable: The JSON schema to the agent
    - `tools_type` 'document' | 'image' | 'video' | 'multimodal', nullable: The type of tools to use for the agent
    - `skills` AgentSkill[], nullable: List of agent skills to enable for this execution. Skills provide domain-specific expertise and capabilities.
      - `type` string: The type of the skill. Use 'skill_reference' for DB-stored skills referenced by id/name. Use 'inline' to provide the skill as a base64-encoded zip bundle.
      - `skill_id` string, nullable: The unique identifier of the skill — a UUID or a name string (e.g., 'pillow', 'batch-processing').
      - `skill_name` string, nullable: Human-readable skill name for lookup (e.g., 'invoice-extraction'). Alternative to skill_id. Deprecated in favour of skill_id.
      - `skill_version` union: The version of the skill — an integer (e.g. 2) or 'latest'.
        - integer
        - string
      - `version` union: DEPRECATED: Use 'skill_version' instead. The version of the skill.
        - integer
        - string
      - `name` string, nullable: Human-readable name for the inline skill (used for discovery and logging).
      - `description` string, nullable: Short description of what the inline skill does.
      - `source` InlineSkillSource: Source payload for an inline skill bundle. Follows the OpenAI inline skill format:: { "type": "base64", "media_type": "application/zip", "data": "<base64-encoded-zip>" }
        - `type` 'base64': Encoding type for the inline skill data. Currently only 'base64' is supported.
        - `media_type` string: MIME type of the skill bundle. Must be 'application/zip'.
        - `data` string, required: Base64-encoded zip bundle containing the skill files.
      - `bundle` string, nullable: DEPRECATED: Use 'source.data' instead. Base64-encoded zip bundle containing the skill files (inline skills only).
    - `selected_tools` string[], nullable: List of tool names to use for this agent execution. If provided, only these tools will be loaded. Tool names should match function names exactly.
    - `use_context_cache` boolean: Reuse cached representations of large document/video inputs across calls in the same session to reduce input-token cost and latency.
    - `service_tier` 'auto' | 'default' | 'standard' | 'flex' | 'priority', nullable: Delivery tier for the agent run. `auto`/`default`/`None` resolves to `standard` (baseline 1.0× billing); `flex` is 0.5× billing with higher latency, and `priority` is 1.8× billing with a premium latency SLO.
  - `id` string: Unique identifier of the request.
  - `created_at` string, date-time: Date and time when the request was created (in UTC timezone)
  - `callback_url` string, uri, nullable: The URL to call when the request is completed.
  - `model` union: VLM Run Agent model to use for agent creation. When omitted, the skill's vlmrun.yaml model is used; otherwise the agent default.
    - 'vlmrun-orion-1' | 'vlmrun-orion-1:auto' | 'vlmrun-orion-1:fast' | 'vlmrun-orion-1:pro' | 'vlmrun-orion-2' | 'vlmrun-orion-2:auto' | 'vlmrun-orion-2:pro'
    - string
  - `name` string, nullable: Name of the agent. If not provided, a pretty-name will be generated.
  - `inputs` AgentExecutionInputs: Base class for agent execution inputs. Users can subclass this to create typed input models for their agents. For example: class MyAgentInputs(AgentExecutionInputs): image: MessageContent prompt: str request = AgentExecutionRequest( name="my-agent", inputs=MyAgentInputs(image=..., prompt=...) )

## Response `200`

Successful Response

- AgentCreationResponse: Response to the agent creation request.
  - `id` string, required: ID of the agent
  - `name` string, required: Name of the agent
  - `status` 'pending' | 'enqueued' | 'running' | 'completed' | 'failed' | 'paused': The status of the job.
  - `created_at` string, date-time, required: Date and time when the agent was created (in UTC timezone)
  - `updated_at` string, date-time, required: Date and time when the agent was updated (in UTC timezone)

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/vlm/apis/vlm-run-unified-server.md) · [All operations](https://skmtc.dev/vlm/apis/vlm-run-unified-server/llms.txt) · [OpenAPI document](https://skmtc.dev/vlm/apis/vlm-run-unified-server/revisions/4a68ab36546b?raw)