> ## 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.

# Agent Execution

> Use skills with the agent execution endpoint

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  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,
  )
  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  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,
  });
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  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
    }'
  ```
</CodeGroup>

## Multiple Skills

Pass multiple skills in the `config.skills` array:

```python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
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`](https://github.com/vlm-run/vlmrun-python-sdk/blob/main/vlmrun/client/types.py) to build an inline `AgentSkill` from a local directory in one call:

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  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,
  )
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"dark-plus"}}
  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
    }'
  ```
</CodeGroup>

`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](/skills/spec/overview#inline-skill-bundles) for details on bundle contents and the [Reference](/skills/reference#inline-skill-fields) for `AgentSkill` inline fields.

## Synchronous vs Batch

* **Synchronous** (`batch=False`): Blocks until the agent completes. Best for short tasks.
* **Batch** (`batch=True`): Returns immediately with a prediction ID. Poll for results. Best for long-running tasks like video analysis.

```python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# 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)
```