---
title: "Execute Agent"
method: POST
path: "/v1/agent/execute"
tags: ["agent"]
---

# Execute Agent

`POST /v1/agent/execute`

## 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/execute`
- Auth: HTTP bearer

## Request body

- AgentExecutionRequest: Request to execute an agent.
  - `metadata` RequestMetadata: Metadata for the request. Typically captured in {"vlmrun": {"metadata": {"environment": <environment>, ...}}.
    - `environment` 'dev' | 'staging' | 'prod': The environment where the request was made.
    - `session_id` string, nullable: The session ID of the request
    - `allow_logging` boolean: Whether to enable logs for this request.
    - `allow_training` boolean: Whether the file can be used for training
    - `allow_retention` boolean: Whether to allow retention of the data
    - `extra` object: Extra metadata for the request (e.g. `dataset_id`, `subset_id`).
  - `config` AgentExecutionConfig: Configuration for the agent execution request.
    - `prompt` string, nullable: The prompt to guide the execution 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.
    - `mode` 'agent' | 'program': Orion-2 only (ignored for other models and the document/image/video generate APIs). `agent` (default): run the full LLM agent loop (the agent decides at runtime). `program`: run cached skill pipeline.py as fixed code when available.
  - `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 execution. 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, we use the prompt to identify the unique agent.
  - `batch` boolean: Whether to process the document in batch mode (async).
  - `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

- AgentExecutionResponse: Response to the agent execution request.
  - `usage` CreditUsageResponse: Response model for credit usage metrics.
    - `elements_processed` integer, nullable: Number of elements processed.
    - `element_type` 'image' | 'page' | 'video' | 'audio', nullable: The type of element processed (e.g. image, page, video, audio).
    - `credits_used` integer, nullable: Amount of total credits used.
    - `steps` integer, nullable: Number of steps processed, in case of agentic execution.
    - `message` string, nullable: The message from the credit usage job.
    - `duration_seconds` integer: Duration of the request in seconds.
    - `service_tier` string, nullable: Delivery tier (standard, priority, flex).
    - `mode_multiplier` number, nullable: Pricing multiplier applied to standard cost.
    - `standard_cost_dollars` number, nullable: Pre-multiplier customer cost in USD, derived from tokens and unit rates.
    - `cost_dollars` number, nullable: Effective customer cost in USD after the service-tier multiplier.
    - `savings_dollars` number, nullable: Discount in USD when using flex (standard_cost_dollars - cost_dollars).
  - `id` string: Unique identifier of the agent execution response.
  - `name` string, required: Name of the agent
  - `response` unknown
  - `execution_mode` 'agent' | 'program': How the execution ran: `program` when a cached skill pipeline.py ran as fixed code (no LLM agent loop), else `agent`. Always `agent` for non-Orion-2 models.
  - `status` 'pending' | 'enqueued' | 'running' | 'completed' | 'failed' | 'paused': The status of the job.
  - `fallback` boolean: True when the JSON was produced by a fallback model. False when the primary model succeeded.
  - `created_at` string, date-time: Date and time when the execution was created (in UTC timezone)
  - `completed_at` string, date-time, nullable: Date and time when the execution was completed (in UTC timezone)

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-19** `4a68ab36546b`: 1 info
  - added the optional property `fallback` to the response with the `200` status

[Operation history](https://skmtc.dev/vlm/apis/vlm-run-unified-server/changes/v1/agent/execute/post.md)

---

[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)