Chat Completions

Pass skills in the skills parameter when creating chat completions:

from vlmrun.client import VLMRun
from vlmrun.client.types import AgentSkill

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

response = client.agent.completions.create(
    model="vlmrun-orion-1:auto",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extract data from this document."},
                {"type": "file_url", "file_url": {"url": "https://example.com/invoice.pdf"}}
            ]
        }
    ],
    skills=[AgentSkill(skill_name="invoice-extraction")],
)

import { VlmRun } from "vlmrun";

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

const response = await client.agent.completions.create({
    model: "vlmrun-orion-1:auto",
    messages: [
        {
            role: "user",
            content: [
                { type: "text", text: "Extract data from this document." },
                { type: "file_url", file_url: { url: "https://example.com/invoice.pdf" } }
            ]
        }
    ],
    skills: [{ skillName: "invoice-extraction" }],
});

curl -X POST https://api.vlm.run/v1/openai/chat/completions \
  -H "Authorization: Bearer <VLMRUN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vlmrun-orion-1:auto",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Extract data from this document."},
          {"type": "file_url", "file_url": {"url": "https://example.com/invoice.pdf"}}
        ]
      }
    ],
    "skills": [{"skill_name": "invoice-extraction"}]
  }'

Multiple Skills

You can pass multiple skills in a single request. The agent applies all skills during execution:

response = client.agent.completions.create(
    model="vlmrun-orion-1:auto",
    messages=[...],
    skills=[
        AgentSkill(skill_name="invoice-extraction"),
        AgentSkill(skill_name="line-item-validation"),
    ],
)

Inline Skills

Instead of referencing a server-stored skill, you can send a 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 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.completions.create(
    model="vlmrun-orion-1:auto",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Extract data from this invoice."},
                {"type": "file_url", "file_url": {"url": "https://example.com/invoice.pdf"}}
            ]
        }
    ],
    skills=[skill],
)

curl -X POST https://api.vlm.run/v1/openai/chat/completions \
  -H "Authorization: Bearer <VLMRUN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vlmrun-orion-1:auto",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Extract data from this invoice."},
          {"type": "file_url", "file_url": {"url": "https://example.com/invoice.pdf"}}
        ]
      }
    ],
    "skills": [{
      "type": "inline",
      "name": "invoice-extraction",
      "description": "Extract structured data from invoices",
      "source": {
        "type": "base64",
        "media_type": "application/zip",
        "data": "<base64-encoded-zip>"
      }
    }]
  }'

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.

You can mix referenced and inline skills in the same request. Each entry in the skills array is resolved independently.

Pinned Versions

Pin a specific skill version for reproducible results:

response = client.agent.completions.create(
    model="vlmrun-orion-1:auto",
    messages=[...],
    skills=[AgentSkill(skill_name="patient-referral", skill_version="20260219-abc123")],
)

See Version Pinning for details.

Overview

Specification

Using Skills

Managing Skills

Chat Completions

Multiple Skills

Inline Skills

Pinned Versions

​Multiple Skills

​Inline Skills

​Pinned Versions

Multiple Skills

Inline Skills

Pinned Versions