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

# Python SDK API Reference

> Complete API reference for RunAgent Python SDK

## RunAgentClient

Synchronous client for interacting with RunAgent.

### Constructor

```python theme={null}
RunAgentClient(
    agent_id: str,
    api_key: Optional[str] = None,
    base_url: str = "https://api.run-agent.ai",
    timeout: int = 30,
    max_retries: int = 3,
    headers: Optional[Dict[str, str]] = None
)
```

#### Parameters

* `agent_id` (str): The ID of your deployed agent
* `api_key` (str, optional): API key for authentication
* `base_url` (str): Base URL for API endpoints
* `timeout` (int): Request timeout in seconds
* `max_retries` (int): Maximum number of retry attempts
* `headers` (dict, optional): Additional headers

### Methods

#### run\_generic

```python theme={null}
run_generic(
    input_data: Dict[str, Any],
    timeout: Optional[int] = None,
    headers: Optional[Dict[str, str]] = None
) -> Dict[str, Any]
```

Run agent with generic input/output.

**Parameters:**

* `input_data`: Dictionary containing input for the agent
* `timeout`: Override default timeout
* `headers`: Additional headers for this request

**Returns:** Dictionary with agent response

#### run\_generic\_stream

```python theme={null}
run_generic_stream(
    input_data: Dict[str, Any],
    timeout: Optional[int] = None,
    headers: Optional[Dict[str, str]] = None
) -> Generator[str, None, None]
```

Stream agent responses in real-time.

**Parameters:**

* `input_data`: Dictionary containing input for the agent
* `timeout`: Override default timeout
* `headers`: Additional headers for this request

**Returns:** Generator yielding response chunks

## AsyncRunAgentClient

Asynchronous client for interacting with RunAgent.

### Constructor

```python theme={null}
AsyncRunAgentClient(
    agent_id: str,
    api_key: Optional[str] = None,
    base_url: str = "https://api.run-agent.ai",
    timeout: int = 30,
    max_retries: int = 3,
    headers: Optional[Dict[str, str]] = None
)
```

Parameters are the same as `RunAgentClient`.

### Methods

#### run\_generic

```python theme={null}
async run_generic(
    input_data: Dict[str, Any],
    timeout: Optional[int] = None,
    headers: Optional[Dict[str, str]] = None
) -> Dict[str, Any]
```

Async version of run\_generic.

#### run\_generic\_stream

```python theme={null}
async run_generic_stream(
    input_data: Dict[str, Any],
    timeout: Optional[int] = None,
    headers: Optional[Dict[str, str]] = None
) -> AsyncGenerator[str, None]
```

Async generator for streaming responses.

## Exceptions

### RunAgentError

Base exception for all RunAgent errors.

```python theme={null}
class RunAgentError(Exception):
    def __init__(self, message: str, code: Optional[str] = None, details: Optional[Dict] = None):
        self.message = message
        self.code = code
        self.details = details
```

### Specific Exceptions

* `AuthenticationError`: Invalid or missing API key
* `AgentNotFoundError`: Agent ID doesn't exist
* `ValidationError`: Invalid input data
* `RateLimitError`: Too many requests
* `TimeoutError`: Request timed out
* `NetworkError`: Network-related errors

## Type Definitions

```python theme={null}
from typing import Dict, Any, Optional, Generator, AsyncGenerator

# Input/Output types
InputData = Dict[str, Any]
OutputData = Dict[str, Any]

# Stream types
StreamChunk = str
StreamGenerator = Generator[StreamChunk, None, None]
AsyncStreamGenerator = AsyncGenerator[StreamChunk, None]
```

## Configuration

### Environment Variables

* `RUNAGENT_API_KEY`: Default API key
* `RUNAGENT_API_URL`: Override base URL
* `RUNAGENT_TIMEOUT`: Default timeout
* `RUNAGENT_LOG_LEVEL`: Logging level

### Configuration File

Location: `~/.runagent/config.json`

```json theme={null}
{
  "api_key": "your-api-key",
  "api_url": "https://api.run-agent.ai",
  "timeout": 30,
  "retry_config": {
    "max_retries": 3,
    "retry_delay": 1.0,
    "retry_backoff": 2.0
  }
}
```

## Complete Example

```python theme={null}
from runagent import RunAgentClient, RunAgentError
import asyncio

# Synchronous example
def sync_example():
    client = RunAgentClient(agent_id="agent-123")
    
    try:
        # Simple request
        result = client.run_generic({"query": "Hello"})
        print(f"Response: {result}")
        
        # Streaming
        for chunk in client.run_generic_stream({"query": "Tell a story"}):
            print(chunk, end="")
            
    except RunAgentError as e:
        print(f"Error: {e.message}")

# Asynchronous example
async def async_example():
    from runagent import AsyncRunAgentClient
    
    client = AsyncRunAgentClient(agent_id="agent-123")
    
    # Concurrent requests
    tasks = [
        client.run_generic({"query": f"Question {i}"})
        for i in range(5)
    ]
    results = await asyncio.gather(*tasks)
    
    # Streaming
    async for chunk in client.run_generic_stream({"query": "Stream test"}):
        print(chunk, end="")

# Run examples
sync_example()
asyncio.run(async_example())
```

## See Also

* [Getting Started](/sdk/python/getting-started) - Introduction to the SDK
* [Examples](/resources/examples) - More code examples
* [API Introduction](/api-reference/introduction) - REST API documentation