> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vlm.run/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Agent
```python Python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
!pip install vlmrun
from pydantic import BaseModel, Field
import datetime
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentCreationResponse, AgentCreationConfig, AgentExecutionResponse
from vlmrun.types import MessageContent, FileUrl
# Define a Pydantic model for the execution inputs
class ExecutionInputs(BaseModel):
file: MessageContent = Field(..., description="The file to extract data from")
# Define a Pydantic model for the response
class Invoice(BaseModel):
invoice_id: str = Field(..., description="The ID of the invoice")
invoice_date: datetime.date = Field(..., description="The date of the invoice")
total_amount: float = Field(..., description="The total amount of the invoice")
# Initialize the client
client = VLMRun(api_key="")
# Create the agent using a prompt
response: AgentCreationResponse = client.agent.create(
name="invoice-extractor", # Optional name
inputs=ExecutionInputs(file=MessageContent(type="file_url", file_url=FileUrl(url="https://example.com/invoice.pdf"))), # Optional test inputs
config=AgentCreationConfig(prompt="Extract the invoice_id, date and amount from the invoice.", response_model=Invoice),
)
```
```javascript Node.js theme={"theme":{"light":"github-light","dark":"dark-plus"}}
npm install vlmrun zod
import { VlmRun } from 'vlmrun';
import { z } from 'zod';
// Define a Zod schema for the execution inputs
const ExecutionInputsSchema = z.object({
file: z.object({
type: z.literal("file_url"),
file_url: z.object({
url: z.string()
})
}).describe("The file to extract data from")
});
// Define a Zod schema for the response
const InvoiceSchema = z.object({
invoice_id: z.string().describe("The ID of the invoice"),
invoice_date: z.string().date().describe("The date of the invoice"),
total_amount: z.number().describe("The total amount of the invoice")
});
// Initialize the client
const client = new VlmRun({
baseUrl: "https://api.vlm.run/v1",
apiKey: ""
});
// Create the agent using a prompt
const response = await client.agent.create({
name: "invoice-extractor", // Optional name
inputs: { // Optional test inputs
file: {
type: "file_url",
file_url: {
url: "https://example.com/invoice.pdf"
}
}
},
config: {
prompt: "Extract the invoice_id, date and amount from the invoice.",
json_schema: JSON.stringify(InvoiceSchema.shape)
}
});
```
## OpenAPI
````yaml POST /v1/agent/create
openapi: 3.1.0
info:
title: VLM Run Unified Server
description: Unified server for VLM Run Agent and API
termsOfService: https://vlm.run/terms-of-service
contact:
name: VLM Run Support Team
url: https://vlm.run/
email: support@vlm.run
version: 2026-05-19.0
servers: []
security: []
paths:
/v1/agent/create:
post:
tags:
- agent
summary: ' Create Agent'
operationId: _create_agent_v1_agent_create_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AgentCreationRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AgentCreationResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
AgentCreationRequest:
properties:
config:
$ref: '#/components/schemas/AgentCreationConfig'
description: The configuration for the agent creation request.
id:
type: string
title: Id
description: Unique identifier of the request.
created_at:
type: string
format: date-time
title: Created At
description: Date and time when the request was created (in UTC timezone)
callback_url:
anyOf:
- type: string
minLength: 1
format: uri
- type: 'null'
title: Callback Url
description: The URL to call when the request is completed.
model:
anyOf:
- type: string
enum:
- vlmrun-orion-1
- vlmrun-orion-1:lite
- vlmrun-orion-1:auto
- vlmrun-orion-1:fast
- vlmrun-orion-1:pro
- vlmrun-orion-2
- vlmrun-orion-2:lite
- vlmrun-orion-2:auto
- vlmrun-orion-2:qwen3.6-35b-a3b
- vlmrun-orion-2:gemma4-26b-a4b
- vlmrun-orion-2:kimi-2.6
- vlmrun-orion-2:gpt-5.5
- vlmrun-orion-2:opus-4.8
- vlmrun-orion-2:gemini-flash-3.5
- vlmrun-orion-2:fast
- vlmrun-orion-2:pro
- type: 'null'
title: Model
description: >-
VLM Run Agent model to use for agent creation. When omitted, the
skill's vlmrun.yaml model is used; otherwise the agent default.
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: Name of the agent. If not provided, a pretty-name will be generated.
inputs:
anyOf:
- $ref: '#/components/schemas/AgentExecutionInputs'
- type: 'null'
description: The inputs to the agent.
type: object
title: AgentCreationRequest
description: Request to create an agent.
AgentCreationResponse:
properties:
id:
type: string
title: Id
description: ID of the agent
name:
type: string
title: Name
description: Name of the agent
status:
type: string
enum:
- pending
- enqueued
- running
- completed
- failed
- paused
title: Status
description: The status of the job.
default: pending
created_at:
type: string
format: date-time
title: Created At
description: Date and time when the agent was created (in UTC timezone)
updated_at:
type: string
format: date-time
title: Updated At
description: Date and time when the agent was updated (in UTC timezone)
type: object
required:
- id
- name
- created_at
- updated_at
title: AgentCreationResponse
description: Response to the agent creation request.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
AgentCreationConfig:
properties:
prompt:
anyOf:
- type: string
- type: 'null'
title: Prompt
description: The prompt to guide the creation of the agent.
json_schema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Json Schema
description: The JSON schema to the agent
tools_type:
anyOf:
- type: string
enum:
- document
- image
- video
- multimodal
- type: 'null'
title: Tools Type
description: The type of tools to use for the agent
skills:
anyOf:
- items:
$ref: '#/components/schemas/AgentSkill'
type: array
- type: 'null'
title: Skills
description: >-
List of agent skills to enable for this execution. Skills provide
domain-specific expertise and capabilities.
selected_tools:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Selected Tools
description: >-
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:
type: boolean
title: Use Context Cache
description: >-
Reuse cached representations of large document/video inputs across
calls in the same session to reduce input-token cost and latency.
default: true
service_tier:
anyOf:
- type: string
enum:
- auto
- default
- standard
- flex
- priority
- type: 'null'
title: Service Tier
description: >-
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.
type: object
title: AgentCreationConfig
description: Configuration for the agent creation request.
AgentExecutionInputs:
properties: {}
additionalProperties: true
type: object
title: AgentExecutionInputs
description: |-
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=...)
)
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
AgentSkill:
properties:
type:
type: string
title: Type
description: >-
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.
default: skill_reference
skill_id:
anyOf:
- type: string
- type: 'null'
title: Skill Id
description: >-
The unique identifier of the skill — a UUID or a name string (e.g.,
'pillow', 'batch-processing').
skill_name:
anyOf:
- type: string
- type: 'null'
title: Skill Name
description: >-
Human-readable skill name for lookup (e.g., 'invoice-extraction').
Alternative to skill_id. Deprecated in favour of skill_id.
skill_version:
anyOf:
- type: integer
- type: string
title: Skill Version
description: The version of the skill — an integer (e.g. 2) or 'latest'.
default: latest
version:
anyOf:
- type: integer
- type: string
- type: 'null'
title: Version
description: 'DEPRECATED: Use ''skill_version'' instead. The version of the skill.'
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: >-
Human-readable name for the inline skill (used for discovery and
logging).
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Short description of what the inline skill does.
source:
anyOf:
- $ref: '#/components/schemas/InlineSkillSource'
- type: 'null'
description: >-
Source payload for inline skills. Contains the base64-encoded zip
bundle with type, media_type, and data fields.
bundle:
anyOf:
- type: string
- type: 'null'
title: Bundle
description: >-
DEPRECATED: Use 'source.data' instead. Base64-encoded zip bundle
containing the skill files (inline skills only).
type: object
title: AgentSkill
description: >-
A modular capability that extends the agent's functionality.
Agent Skills are reusable, filesystem-based resources that provide the
agent
with domain-specific expertise: workflows, context, and best practices.
Each skill packages instructions, metadata, and optional resources
(scripts,
templates, snippets) that the agent uses automatically when relevant.
Two modes are supported:
1. **Referenced skills** (``type="skill_reference"``) – Provide
``skill_id``
(UUID or name) and optionally ``skill_version`` (integer or ``"latest"``).
.. code-block:: json
{"type": "skill_reference", "skill_id": "pillow", "skill_version": "latest"}
2. **Inline skills** (``type="inline"``) – Supply ``name``,
``description``,
and a ``source`` object containing the base64-encoded zip bundle. The zip
must contain exactly one ``SKILL.md`` file. No database lookup is required.
.. code-block:: json
{
"type": "inline",
"name": "csv-insights",
"description": "Summarize CSV files.",
"source": {
"type": "base64",
"media_type": "application/zip",
"data": ""
}
}
Legacy format with flat ``bundle`` field is also accepted for backward
compatibility.
InlineSkillSource:
properties:
type:
type: string
const: base64
title: Type
description: >-
Encoding type for the inline skill data. Currently only 'base64' is
supported.
default: base64
media_type:
type: string
title: Media Type
description: MIME type of the skill bundle. Must be 'application/zip'.
default: application/zip
data:
type: string
title: Data
description: Base64-encoded zip bundle containing the skill files.
type: object
required:
- data
title: InlineSkillSource
description: |-
Source payload for an inline skill bundle.
Follows the OpenAI inline skill format::
{
"type": "base64",
"media_type": "application/zip",
"data": ""
}
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````