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

Agent name and version in format “agent-name:version”. Required if not using inline config.
Input files and parameters for the agent. Must include “file” key with file URL.
Inline agent configuration for one-time execution without creating a persistent agent.
Execution priority: “low”, “normal”, or “high”. Higher priority executions are processed first.

​
Example: Execute Agent by Name

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

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

# 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={
        "file": file.public_url
    }
)

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": "https://storage.vlm.run/files/invoice.pdf"
  }
}

​
Example: Execute with Inline Prompt

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

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

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

# Execute with inline prompt
response: AgentExecutionResponse = client.agent.execute(
    inputs={
        "file": file.public_url
    },
    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": "https://storage.vlm.run/files/receipt.jpg"
  },
  "config": {
    "prompt": "Extract the store name, date, items purchased, and total amount."
  }
}

​
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: 
from pathlib import Path
from vlmrun.client import VLMRun
import time

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

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

# Step 2: Execute agent
print("Executing agent...")
execution = client.agent.execute(
    name="invoice-extractor:v1",
    inputs={"file": file.public_url}
)
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"))
    ),
    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