Skip to main content

​
Python SDK Examples

​
Complete End-to-End Example

This example shows the full workflow: creating an agent, running a job, and getting results. 
#!/usr/bin/env python3
"""
Complete end-to-end example: Create an agent and run a job
"""
import os
from roe import RoeClient

# Set your credentials as environment variables
# export ROE_API_KEY="your-api-key-here"
# export ROE_ORGANIZATION_ID="your-organization-uuid"

def main():
    # Initialize the client
    client = RoeClient()
    
    # Step 1: Create an agent
    print("Creating agent...")
    agent = client.agents.create(
        name="Document Analyzer",
        engine_class_id="MultimodalExtractionEngine",
        input_definitions=[
            {
                "key": "text",
                "data_type": "text/plain",
                "description": "Text to analyze",
            },
        ],
        engine_config={
            "model": "gpt-5.2-2025-12-11",
            "instruction": "Analyze the provided text and extract key insights.",
            "output_schema": {
                "type": "object",
                "properties": {
                    "summary": {
                        "type": "string",
                        "description": "Brief summary of the text"
                    },
                    "key_insights": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "Key insights from the analysis",
                    },
                    "sentiment": {
                        "type": "string",
                        "description": "Overall sentiment (positive/negative/neutral)"
                    },
                },
                "required": ["summary", "key_insights", "sentiment"]
            },
        },
        version_name="v1",
        description="Initial version of document analyzer",
    )
    
    print(f"✓ Created agent: {agent.name}")
    print(f"  Agent ID: {agent.id}")
    print(f"  Version ID: {agent.current_version_id}")
    
    # Step 2: Run the agent with sample input
    print("\nRunning agent job...")
    job = client.agents.run(
        agent_id=agent.id,
        text="Artificial intelligence is transforming industries worldwide. "
             "Companies are leveraging AI to improve efficiency, reduce costs, "
             "and create innovative products. However, ethical considerations "
             "around data privacy and bias remain critical challenges."
    )
    
    print(f"  Job ID: {job.id}")
    
    # Step 3: Wait for results
    print("  Waiting for results...")
    result = job.wait()
    
    # Step 4: Display results
    print("\n✓ Job completed successfully!")
    print("\nResults:")
    for output in result.outputs:
        print(f"  {output.key}: {output.value}")
    
    print(f"\n✓ Job completed in {result.duration_seconds:.2f} seconds")

if __name__ == "__main__":
    main()

​
Authentication

Set credentials as environment variables: 
export ROE_API_KEY="your-api-key-here"
export ROE_ORGANIZATION_ID="your-organization-uuid"

​
Quick Start

from roe import RoeClient

client = RoeClient()

# List agents
agents = client.agents.list_base_agents()

# Run an agent
job = client.agents.run(
    agent_id="your-agent-uuid",
    text="Hello world"
)
result = job.wait()

# Process results
for output in result.outputs:
    print(f"{output.key}: {output.value}")

​
Batch Processing

batch = client.agents.run_many(
    agent_id="agent-uuid",
    inputs_list=[
        {"text": "Analyze sentiment: I love this!"},
        {"text": "Analyze sentiment: This is terrible."},
    ]
)

results = batch.wait()
for result in results:
    print(result.outputs)

​
File Uploads

# File path (auto-upload)
job = client.agents.run(
    agent_id="agent-uuid",
    document="path/to/file.pdf",
    text="Analyze this document"
)

# Existing Roe file ID
job = client.agents.run(
    agent_id="agent-uuid",
    document="file-uuid-here",
    text="Analyze this document"
)