The RunAgent Python SDK provides a simple and powerful interface for interacting with your deployed agents. It supports both synchronous and asynchronous operations, with built-in streaming capabilities.

​
Installation

Install the SDK using pip: 
pip install runagent
The SDK is included with the main runagent package. No separate installation needed.

​
Quick Start

​
Basic Usage

from runagent import RunAgentClient

# Initialize the client
client = RunAgentClient(agent_id="your-agent-id")

# Simple invocation
result = client.run_generic({
    "query": "What's the capital of France?",
    "context": "Geography question"
})

print(result)

​
With API Key

from runagent import RunAgentClient

# Initialize with API key
client = RunAgentClient(
    agent_id="your-agent-id",
    api_key="your-api-key"  # Optional if set in environment
)

​
Authentication

The SDK supports multiple authentication methods: 
export RUNAGENT_API_KEY="your-api-key"

# SDK will automatically use the environment variable
client = RunAgentClient(agent_id="your-agent-id")

​
Response Formats

​
Standard Response

result = client.run_generic({
    "query": "Explain quantum computing",
    "max_length": 200
})

# Result is a dictionary
print(result["answer"])
print(result["confidence"])
print(result["sources"])

​
Streaming Response

# Stream responses for real-time output
for chunk in client.run_generic_stream({
    "query": "Write a story about AI"
}):
    print(chunk, end="", flush=True)

​
Error Handling

The SDK provides comprehensive error handling: 
from runagent import RunAgentClient, RunAgentError

client = RunAgentClient(agent_id="your-agent-id")

try:
    result = client.run_generic({"query": "Hello"})
except RunAgentError as e:
    print(f"RunAgent error: {e}")
    print(f"Error code: {e.code}")
    print(f"Error details: {e.details}")
except Exception as e:
    print(f"Unexpected error: {e}")

​
Common Error Types

ErrorDescription
AuthenticationErrorInvalid or missing API key
AgentNotFoundErrorAgent ID doesn’t exist
ValidationErrorInvalid input data
TimeoutErrorRequest timed out
RateLimitErrorToo many requests

​
Configuration Options

from runagent import RunAgentClient

client = RunAgentClient(
    agent_id="your-agent-id",
    api_key="your-api-key",
    base_url="https://api.run-agent.ai",  # Custom API endpoint
    timeout=30,  # Request timeout in seconds
    max_retries=3,  # Number of retry attempts
    verify_ssl=True  # SSL certificate verification
)

​
Input Validation

The SDK validates inputs before sending requests: 
# This will raise ValidationError if required fields are missing
try:
    result = client.run_generic({})  # Missing required 'query' field
except ValidationError as e:
    print(f"Validation failed: {e}")

​
Logging

Enable logging for debugging: 
import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

# Now SDK operations will print debug information
client = RunAgentClient(agent_id="your-agent-id")
result = client.run_generic({"query": "Test"})

​
Complete Examples

​
Question-Answering Bot

from runagent import RunAgentClient

def ask_agent(question):
    client = RunAgentClient(agent_id="qa-bot-agent")
    
    try:
        result = client.run_generic({
            "query": question,
            "max_tokens": 500,
            "temperature": 0.7
        })
        return result.get("answer", "No answer available")
    except Exception as e:
        return f"Error: {str(e)}"

# Usage
answer = ask_agent("What is machine learning?")
print(answer)

​
Interactive Chat

from runagent import RunAgentClient

def chat_with_agent():
    client = RunAgentClient(agent_id="chat-agent")
    
    print("Chat started. Type 'quit' to exit.")
    
    while True:
        user_input = input("\nYou: ")
        if user_input.lower() == 'quit':
            break
        
        print("\nAgent: ", end="")
        for chunk in client.run_generic_stream({
            "query": user_input,
            "conversation_id": "session-123"
        }):
            print(chunk, end="", flush=True)
        print()  # New line after response

# Start chat
chat_with_agent()

​
Batch Processing

from runagent import RunAgentClient
import json

def process_batch(items):
    client = RunAgentClient(agent_id="processor-agent")
    results = []
    
    for item in items:
        try:
            result = client.run_generic({
                "data": item,
                "operation": "analyze"
            })
            results.append({
                "input": item,
                "output": result,
                "status": "success"
            })
        except Exception as e:
            results.append({
                "input": item,
                "output": None,
                "status": "error",
                "error": str(e)
            })
    
    return results

# Process multiple items
items = ["data1", "data2", "data3"]
results = process_batch(items)
print(json.dumps(results, indent=2))

​
Best Practices

Reuse Clients

Create client instances once and reuse them for multiple requests

Handle Errors

Always implement proper error handling for production use

Use Streaming

Use streaming for long responses to improve user experience

Set Timeouts

Configure appropriate timeouts based on your agent’s complexity

​
Next Steps

Synchronous Client

Deep dive into synchronous operations

Asynchronous Client

Learn about async/await support

Streaming Responses

Master real-time streaming

API Reference

Complete API documentation