Skip to main content
Agent execution example showing processing workflow

​
Agent Execution

Execute previously created agents on files to extract structured data with consistent, reproducible results. Monitor execution status and retrieve results asynchronously for long-running processing tasks.

​
Key Features

  • Consistent Results: Same agent produces identical output structure across executions
  • Async Processing: Long-running extractions handled asynchronously with status tracking
  • Batch Processing: Execute agents on multiple files efficiently
  • Status Monitoring: Track execution progress from queued to completed
  • Result Retrieval: Access structured results when processing finishes

​
Use Cases

Automated Document Processing

Process invoices, receipts, and forms at scale with consistent extraction

Data Entry Automation

Extract information from scanned documents to eliminate manual entry

Archive Digitization

Convert paper document archives to structured digital data

Multi-Source Integration

Extract data from various document types into a unified format

​
Industry Applications

​
Configuration Options

The following fields can be used when executing an agent. Only inputs is required.
FieldRequiredDescription
nameNoAgent name and version in format agent-name:version. Required if not using inline config
inputsYesA Pydantic BaseModel with typed fields for each input. Files use MessageContent with type: "input_file" and a file_id. Supports multiple files via separate fields
configNoInline agent configuration for one-time execution without creating a persistent agent
priorityNoExecution priority: low, normal, or high. Higher priority executions are processed first. Defaults to normal
toolsetsNoList of tool categories to enable for this execution. Available categories: core, image, image-gen, world_gen, viz, document, video, web

​
Example: Execute Agent by Name

Execute a previously created agent by referencing its name and version: 
from pathlib import Path
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentExecutionResponse
from vlmrun.types import MessageContent

# Initialize the client
client = VLMRun(base_url="https://agent.vlm.run/v1", api_key="<VLMRUN_API_KEY>")

# Define typed inputs
class InvoiceInputs(BaseModel):
    file: MessageContent = Field(..., description="The invoice file to process")

# Upload the file
file = client.files.upload(file=Path("invoice.pdf"))

# Execute the agent by name and version
response: AgentExecutionResponse = client.agent.execute(
    name="invoice-extractor:v1",
    inputs=InvoiceInputs(
        file=MessageContent(type="input_file", file_id=file.id)
    ),
)

print(f"Execution ID: {response.execution_id}")
print(f"Status: {response.status}")

​
Response Format

{
  "execution_id": "exec_abc123xyz",
  "agent_id": "agt_abc123xyz",
  "status": "processing",
  "created_at": "2025-09-30T10:40:00Z",
  "inputs": {
    "file": {"type": "input_file", "file_id": "file_abc123"}
  }
}

​
Example: Execute with Inline Prompt

Execute an agent using an inline prompt without creating a persistent agent: 
from pathlib import Path
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentExecutionResponse, AgentExecutionConfig
from vlmrun.types import MessageContent

client = VLMRun(base_url="https://agent.vlm.run/v1", api_key="<VLMRUN_API_KEY>")

# Define typed inputs
class ReceiptInputs(BaseModel):
    file: MessageContent = Field(..., description="The receipt to process")

# Upload the file
file = client.files.upload(file=Path("receipt.jpg"))

# Execute with inline prompt
response: AgentExecutionResponse = client.agent.execute(
    inputs=ReceiptInputs(
        file=MessageContent(type="input_file", file_id=file.id)
    ),
    config=AgentExecutionConfig(
        prompt="Extract the store name, date, items purchased, and total amount."
    ),
)

print(f"Execution ID: {response.execution_id}")

​
Response Format

{
  "execution_id": "exec_xyz789def",
  "agent_id": null,
  "status": "processing",
  "created_at": "2025-09-30T10:45:00Z",
  "inputs": {
    "file": {"type": "input_file", "file_id": "file_xyz789"}
  },
  "config": {
    "prompt": "Extract the store name, date, items purchased, and total amount."
  }
}

​
Example: Multiple File Inputs

Pass multiple files to an agent by defining a typed input model with separate fields for each file. Each field is a MessageContent with type: "input_file" and the corresponding file_id. 
from pathlib import Path
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentExecutionConfig
from vlmrun.types import MessageContent

client = VLMRun(base_url="https://agent.vlm.run/v1", api_key="<VLMRUN_API_KEY>")

# Define typed inputs for multiple files
class CompareDocsInputs(BaseModel):
    file_1: MessageContent = Field(..., description="First document to compare")
    file_2: MessageContent = Field(..., description="Second document to compare")

# Upload multiple files
file_a = client.files.upload(file=Path("document_page_1.pdf"))
file_b = client.files.upload(file=Path("document_page_2.pdf"))

# Execute with multiple file inputs
response = client.agent.execute(
    inputs=CompareDocsInputs(
        file_1=MessageContent(type="input_file", file_id=file_a.id),
        file_2=MessageContent(type="input_file", file_id=file_b.id),
    ),
    config=AgentExecutionConfig(
        prompt="Compare the two documents and summarize the key differences."
    ),
)

print(f"Execution ID: {response.execution_id}")
The input field names (e.g. file_1, file_2) are flexible — use descriptive names like invoice, receipt, or contract to make your code self-documenting.

​
Checking Execution Status

Monitor execution status and retrieve results when processing completes: 
from vlmrun.client import VLMRun

client = VLMRun(base_url="https://agent.vlm.run/v1", api_key="<VLMRUN_API_KEY>")

# Get execution status
execution = client.agent.executions.get(execution_id="exec_abc123xyz")

print(f"Status: {execution.status}")
if execution.status == "completed":
    print(f"Results: {execution.response}")
elif execution.status == "failed":
    print(f"Error: {execution.error}")

​
Response Format (Completed)

{
  "execution_id": "exec_abc123xyz",
  "agent_id": "agt_abc123xyz",
  "status": "completed",
  "created_at": "2025-09-30T10:40:00Z",
  "updated_at": "2025-09-30T10:40:45Z",
  "processing_time": "45.2s",
  "response": {
    "invoice_id": "INV-2024-001",
    "date": "2024-09-15",
    "total_amount": 1250.00,
    "vendor_name": "Acme Corporation"
  }
}

​
Complete Workflow Example

Full workflow from file upload to result retrieval: 
import time
from pathlib import Path
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.types import MessageContent

# Initialize client
client = VLMRun(base_url="https://agent.vlm.run/v1", api_key="<VLMRUN_API_KEY>")

class FileInput(BaseModel):
    file: MessageContent = Field(..., description="The file to process")

# Step 1: Upload file
print("Uploading file...")
file = client.files.upload(file=Path("invoice.pdf"))
print(f"✓ File uploaded: {file.id}")

# Step 2: Execute agent
print("Executing agent...")
execution = client.agent.execute(
    name="invoice-extractor:v1",
    inputs=FileInput(file=MessageContent(type="input_file", file_id=file.id)),
)
print(f"✓ Execution started: {execution.execution_id}")

# Step 3: Poll for completion
print("Waiting for results...")
while True:
    result = client.agent.executions.get(execution_id=execution.execution_id)

    if result.status == "completed":
        print("✓ Processing complete!")
        print(f"\nExtracted Data:")
        for key, value in result.response.items():
            print(f"  {key}: {value}")
        break
    elif result.status == "failed":
        print(f"✗ Processing failed: {result.error}")
        break

    print("  Processing...", end="\r")
    time.sleep(2)

​
Example Output

Uploading file...
✓ File uploaded: file_abc123
Executing agent...
✓ Execution started: exec_abc123xyz
Waiting for results...
✓ Processing complete!

Extracted Data:
  invoice_id: INV-2024-001
  date: 2024-09-15
  total_amount: 1250.00
  vendor_name: Acme Corporation

​
Execution Statuses

StatusDescription
pendingExecution queued, waiting to start processing
processingAgent is actively processing the file
completedProcessing finished successfully, results available
failedProcessing encountered an error
cancelledExecution was cancelled by user

​
Retrieving Artifacts

Agent executions can generate artifacts such as processed images, videos, or documents. These artifacts are returned as object references (e.g., ImageRef, VideoRef) in the response and can be retrieved using the execution ID. 
from pydantic import BaseModel, Field
from PIL import Image
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentExecutionConfig, ImageUrl
from vlmrun.types import ImageRef, MessageContent

client = VLMRun(base_url="https://agent.vlm.run/v1", api_key="<VLMRUN_API_KEY>")

# Define typed inputs using MessageContent
class ExecutionInputs(BaseModel):
    image: MessageContent = Field(..., description="The input image")

class ImageResponse(BaseModel):
    image: ImageRef = Field(..., description="The processed image")

# Execute an agent that generates an image artifact
execution = client.agent.execute(
    name="image/blur-faces",
    inputs=ExecutionInputs(
        image=MessageContent(type="image_url", image_url=ImageUrl(url="https://example.com/photo.jpg"))  # Images still use image_url
    ),
    config=AgentExecutionConfig(response_model=ImageResponse)
)

# Wait for completion
execution = client.executions.wait(execution.id, timeout=180)

# Parse the response and retrieve the artifact
result = ImageResponse.model_validate(execution.response)
image: Image.Image = client.artifacts.get(
    execution_id=execution.id,
    object_id=result.image.id
)

Artifacts Guide

Learn more about working with artifacts, including supported types and retrieval patterns

​
Best Practices

  • File Formats: Use high-quality PDFs or images (PNG, JPEG) for best results
  • File Size: Keep files under 20MB for optimal processing speed
  • Polling Interval: Poll status every 2-5 seconds to balance responsiveness and API load
  • Error Handling: Always check execution status and handle failures gracefully
  • Batch Processing: Use multiple concurrent executions for processing large batches

Monitor Executions

Track and monitor all your agent executions in the VLM Run dashboard