Agent Execution

Pass skills in the config.skills parameter when executing agents:

from vlmrun.client import VLMRun
from vlmrun.client.types import AgentExecutionConfig, AgentSkill
from vlmrun.types import MessageContent, FileUrl

client = VLMRun(api_key="<VLMRUN_API_KEY>")

response = client.agent.execute(
    inputs={"file": MessageContent(type="file_url", file_url=FileUrl(url="<file-url>"))},
    config=AgentExecutionConfig(
        skills=[AgentSkill(skill_name="patient-referral", skill_version="20260219-abc123")]
    ),
    batch=True,
)

import { VlmRun } from "vlmrun";

const client = new VlmRun({
    apiKey: "<VLMRUN_API_KEY>",
});

const response = await client.agent.execute({
    inputs: { file: { type: "file_url", file_url: { url: "<file-url>" } } },
    config: {
        skills: [{ skillName: "patient-referral", skillVersion: "20260219-abc123" }],
    },
    batch: true,
});

curl -X POST https://api.vlm.run/v1/agent/execute \
  -H "Authorization: Bearer <VLMRUN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"file": {"type": "file_url", "file_url": {"url": "<file-url>"}}},
    "config": {
      "skills": [{"skill_name": "patient-referral", "skill_version": "20260219-abc123"}]
    },
    "batch": true
  }'

Multiple Skills

Pass multiple skills in the config.skills array:

response = client.agent.execute(
    inputs={...},
    config=AgentExecutionConfig(
        skills=[
            AgentSkill(skill_name="document-parsing"),
            AgentSkill(skill_name="data-validation"),
        ]
    ),
    batch=True,
)

Inline Skills

Instead of referencing a server-stored skill by name, you can send the skill bundle directly in the request as a base64-encoded zip. The Python SDK provides AgentSkill.from_directory to build an inline AgentSkill from a local directory in one call:

from pathlib import Path
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentExecutionConfig, AgentSkill

client = VLMRun(api_key="<VLMRUN_API_KEY>")

# Build an inline AgentSkill from a local skill directory
skill = AgentSkill.from_directory(Path("./my-skill"))

response = client.agent.execute(
    inputs={"file": {"type": "file_url", "file_url": {"url": "<file-url>"}}},
    config=AgentExecutionConfig(skills=[skill]),
    batch=True,
)

curl -X POST https://api.vlm.run/v1/agent/execute \
  -H "Authorization: Bearer <VLMRUN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {"file": {"type": "file_url", "file_url": {"url": "<file-url>"}}},
    "config": {
      "skills": [{
        "type": "inline",
        "name": "my-skill",
        "source": {
          "type": "base64",
          "media_type": "application/zip",
          "data": "<base64-encoded-zip>"
        }
      }]
    },
    "batch": true
  }'

AgentSkill.from_directory zips the directory, base64-encodes it, and reads the name and description from the SKILL.md frontmatter automatically. It returns an AgentSkill with type="inline" ready for use. See Skill Structure — Inline Skill Bundles for details on bundle contents and the Reference for AgentSkill inline fields.

Batch Execution

Agent execution currently supports batch mode only.

Batch (batch=True): Returns immediately with a prediction ID. Poll for results. Suitable for both short tasks and long-running tasks like video analysis.
Synchronous (batch=False): Not currently supported. Use batch=True and poll for results.

# Batch execution
response = client.agent.execute(
    inputs={...},
    config=AgentExecutionConfig(
        skills=[AgentSkill(skill_name="video-analysis")]
    ),
    batch=True,
)

# Poll for results
prediction = client.predictions.get(response.id)

Overview

Specification

Using Skills

Managing Skills

Agent Execution

Multiple Skills

Inline Skills

Batch Execution

​Multiple Skills

​Inline Skills

​Batch Execution

Multiple Skills

Inline Skills

Batch Execution