> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roe-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Examples

> Code examples for the Python SDK

# Python SDK Examples

## Complete End-to-End Example

This example shows the full workflow: creating an agent, running a job, and getting results.

```python theme={null}
#!/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}")

if __name__ == "__main__":
    main()
```

## Authentication

Set credentials as environment variables:

```bash theme={null}
export ROE_API_KEY="your-api-key-here"
export ROE_ORGANIZATION_ID="your-organization-uuid"
```

## Quick Start

```python theme={null}
from roe import RoeClient

client = RoeClient()

# List agents
agents_page = client.agents.list()
agents = agents_page.results

# 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

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

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

## File Uploads

```python theme={null}
# 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"
)
```