Robutler Python SDK

The official Python client for the Robutler Platform provides comprehensive access to all backend services using a modern object-oriented design with hierarchical resources and typed model objects.

Installation

pip install robutler

Quick Start

from robutler.api.client import RobutlerClient, RobutlerAPIError

# Modern object-oriented usage
async with RobutlerClient() as client:
    try:
        # Get user information - returns UserProfile object
        user = await client.user.get()
        print(f"Welcome {user.name} ({user.email})!")
        print(f"Plan: {user.plan_name}")
        print(f"Available credits: {user.available_credits}")

        # List agents - returns List[Agent]
        agents = await client.agents.list()
        for agent in agents:
            print(f"Agent: {agent.name} (Model: {agent.model})")

        # Get content files - returns List[ContentFile]
        content_files = await client.content.list()
        for file in content_files:
            print(f"File: {file.name} ({file.size_formatted})")

    except RobutlerAPIError as e:
        print(f"API Error: {e} (Status: {e.status_code})")

Environment Configuration

Set your API key:

# Required: Your Robutler API key
export WEBAGENTS_API_KEY="your-api-key"

Get your WEBAGENTS_API_KEY at https://robutler.ai/developer

API Reference

The client provides hierarchical access to all Robutler Platform services through intuitive resource objects. All methods return typed model objects for clean, IDE-friendly development.

Main Client

robutler.api.client.RobutlerClient

Main API client for the Robutler Platform.

Provides hierarchical access to all Robutler Platform services through intuitive resource objects. All methods return typed model objects for clean, IDE-friendly development.

The client supports automatic retry logic, connection pooling, and comprehensive error handling.

Attributes:

Name	Type	Description
`agents`		Agent management operations (AgentsResource)
`content`		Content file operations (ContentResource)
`user`		User profile and credit operations (UserResource)
`api_keys`		API key management operations (ApiKeysResource)
`tokens`		Payment token operations (TokensResource)
`facilitator`		x402 facilitator operations (FacilitatorResource)
`intents`		Intent publishing operations (IntentsResource)

Environment Variables

WEBAGENTS_API_KEY: Your Robutler API key (required) ROBUTLER_API_URL: Base URL for Robutler API (optional) ROBUTLER_INTERNAL_API_URL: Internal cluster URL (optional)

Example

# Basic usage
async with RobutlerClient() as client:
    # Get user information
    user = await client.user.get()
    print(f"Welcome {user.name}!")

    # List agents
    agents = await client.agents.list()
    for agent in agents:
        print(f"Agent: {agent.name}")

    # Get content files
    files = await client.content.list()
    for file in files:
        print(f"File: {file.name} ({file.size_formatted})")

Raises:

Type	Description
`RobutlerAPIError`	When API requests fail
`ValueError`	When required configuration is missing

agents `instance-attribute`

agents = AgentsResource(self)

content `instance-attribute`

content = ContentResource(self)

user `instance-attribute`

user = UserResource(self)

api_keys `instance-attribute`

api_keys = ApiKeysResource(self)

tokens `instance-attribute`

tokens = TokensResource(self)

intents `instance-attribute`

intents = IntentsResource(self)

init

__init__(api_key: Optional[str] = None, base_url: Optional[str] = None, timeout: int = 30, max_retries: int = 3)

Initialize the Robutler API client.

Parameters:

Name	Type	Description	Default
`api_key`	`Optional[str]`	Your Robutler API key. If not provided, will use WEBAGENTS_API_KEY environment variable.	`None`
`base_url`	`Optional[str]`	Base URL for the Robutler API. If not provided, will try ROBUTLER_INTERNAL_API_URL, then ROBUTLER_API_URL, then default to https://robutler.ai	`None`
`timeout`	`int`	Request timeout in seconds (default: 30)	`30`
`max_retries`	`int`	Maximum number of retries for failed requests (default: 3)	`3`

Raises:

Type	Description
`ValueError`	If no API key is provided via parameter or environment

Example

# Using environment variables (recommended)
client = RobutlerClient()

# Explicit configuration
client = RobutlerClient(
    api_key="your-api-key",
    base_url="https://api.robutler.ai",
    timeout=60
)

close `async`

close()

Close the HTTP session

Resources

Agent Management

robutler.api.client.AgentsResource

Resource for managing AI agents.

Provides methods for creating, listing, updating, and deleting agents, as well as agent discovery and search capabilities.

This resource is accessed via client.agents and returns typed Agent objects for clean attribute access.

Example

# List all agents
agents = await client.agents.list()

# Get specific agent
agent = await client.agents.get_by_name("my-assistant")

# Create new agent
new_agent = await client.agents.create({
    "name": "helper",
    "instructions": "You are a helpful assistant",
    "model": "gpt-4o-mini"
})

# Search for agents
results = await client.agents.search("data analysis")

list `async`

list() -> List[Agent]

List all agents owned by the current user.

Returns:

Type	Description
`List[Agent]`	List of Agent objects with full agent details

Raises:

Type	Description
`RobutlerAPIError`	If the request fails

Example

agents = await client.agents.list()
for agent in agents:
    print(f"{agent.name}: {agent.description}")

get_by_name `async`

get_by_name(name: str) -> Agent

Get agent by name - returns Agent object

get_by_id `async`

get_by_id(agent_id: str) -> Agent

Get agent by ID - returns Agent object

get `async`

get(agent_id: str) -> AgentResource

Get agent resource by ID

create `async`

create(agent_data: Dict[str, Any]) -> Agent

Create a new AI agent.

Parameters:

Name	Type	Description	Default
`agent_data`	`Dict[str, Any]`	Agent configuration dictionary containing: - name (str): Agent name (required) - instructions (str): System instructions (required) - model (str): AI model to use (default: "gpt-4o-mini") - description (str): Agent description for discovery - intents (List[str]): Published intent names - isPublic (bool): Whether agent is publicly discoverable - canTalkToOtherAgents (bool): Can this agent call others - otherAgentsCanTalk (bool): Can others call this agent	required

Returns:

Type	Description
`Agent`	Created Agent object

Raises:

Type	Description
`RobutlerAPIError`	If creation fails

Example

agent = await client.agents.create({
    "name": "data-analyst",
    "instructions": "You analyze data and create reports",
    "model": "gpt-4o",
    "description": "Specialized in data analysis",
    "isPublic": True
})
print(f"Created agent: {agent.id}")

update `async`

update(agent_id: str, agent_data: Dict[str, Any]) -> Agent

Update an existing agent - returns updated Agent object

delete `async`

delete(agent_id: str) -> bool

Delete an agent - returns True if successful

search `async`

search(query: str, max_results: int = 10, mode: str = 'semantic', min_similarity: float = 0.7) -> List[Dict[str, Any]]

Search for agents using semantic search.

Searches across agent names, descriptions, and intents to find relevant agents based on the query.

Parameters:

Name	Type	Description	Default
`query`	`str`	Search query string	required
`max_results`	`int`	Maximum number of results to return (default: 10)	`10`
`mode`	`str`	Search mode, currently 'semantic' (default: 'semantic')	`'semantic'`
`min_similarity`	`float`	Minimum similarity threshold (default: 0.7)	`0.7`

Returns:

Type	Description
`List[Dict[str, Any]]`	List of agent search result dictionaries

Raises:

Type	Description
`RobutlerAPIError`	If search fails

Example

# Find agents that can help with data analysis
results = await client.agents.search("data analysis", max_results=5)
for result in results:
    agent_data = result.get('agent', {})
    print(f"Found: {agent_data.get('name')} - {agent_data.get('description')}")

discover `async`

discover(capabilities: List[str], max_results: int = 10) -> List[Dict[str, Any]]

Discover agents by capabilities - returns list of agent results

find_similar `async`

find_similar(agent_id: str, max_results: int = 10) -> List[Dict[str, Any]]

Find similar agents - returns list of agent results

Content Management

robutler.api.client.ContentResource

Resource for managing content files and agent access.

Provides methods for uploading, listing, and managing content files, as well as controlling agent access to content.

Content files can be marked as 'public' (agent-accessible) or 'private' (user-only). Public files are automatically served through the chat frontend for agent consumption.

Example

# Upload a file
with open("document.pdf", "rb") as f:
    file = await client.content.upload(
        file_data=f.read(),
        filename="document.pdf",
        visibility="public"
    )

# List user's files
files = await client.content.list()

# Get agent-accessible files only
agent_files = await client.content.agent_access()

agent_access `async`

agent_access(visibility: str = 'public') -> List[ContentFile]

Get agent-accessible content - returns list of ContentFile objects

Agent ID is automatically inferred from the API key used for authentication.

list `async`

list(visibility: Optional[str] = None, tags: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None) -> List[ContentFile]

List user's content files - returns list of ContentFile objects

upload `async`

upload(file_data: bytes, filename: str, visibility: str = 'private') -> ContentFile

Upload content file - returns ContentFile object

delete `async`

delete(file_id: str) -> bool

Delete content file - returns True if successful

User Management

robutler.api.client.UserResource

User resource for hierarchical API access

get `async`

get() -> UserProfile

Get current user profile - returns UserProfile object

credits `async`

credits() -> Decimal

Get user's available credits - returns Decimal

transactions `async`

transactions(limit: int = 50) -> List[TransactionInfo]

Get user's transaction history - returns list of TransactionInfo objects

Model Objects

Agent

robutler.api.client.Agent

Represents a Robutler AI agent with typed attribute access.

This model provides clean, typed access to agent properties without requiring dictionary lookups or .get() calls.

Attributes:

Name	Type	Description
`id`	`str`	Unique agent identifier
`name`	`str`	Human-readable agent name
`instructions`	`str`	System instructions for the agent
`model`	`str`	AI model used (e.g., 'gpt-4o-mini')
`intents`	`List[str]`	List of published intent names
`can_use_other_agents`	`bool`	Whether this agent can call other agents
`other_agents_can_talk`	`bool`	Whether other agents can call this agent
`credits_per_token`	`Optional[float]`	Cost per token for using this agent
`minimum_balance`	`Optional[float]`	Minimum balance required to use this agent
`agent_pricing_percent`	`Optional[float]`	Percentage of pricing that goes to agent owner
`is_public`	`bool`	Whether the agent is publicly discoverable
`description`	`str`	Agent description for discovery
`avatar_url`	`Optional[str]`	URL to agent's avatar image
`greeting_message`	`Optional[str]`	Welcome message from the agent
`suggested_actions`	`List[str]`	List of suggested user actions
`greeting_image_mobile`	`Optional[str]`	Mobile greeting image URL
`greeting_image_desktop`	`Optional[str]`	Desktop greeting image URL
`skills`	`Optional[Dict[str, Any]]`	Agent's configured skills and capabilities
`api_key_encrypted`	`Optional[str]`	Encrypted API key for the agent

Example

agents = await client.agents.list()
for agent in agents:
    print(f"Agent: {agent.name} using {agent.model}")
    if agent.is_public:
        print(f"Description: {agent.description}")

to_dict

to_dict() -> Dict[str, Any]

Convert back to dictionary format - returns the agent data only

get_full_data

get_full_data() -> Dict[str, Any]

Get the full raw data structure

Content File

robutler.api.client.ContentFile

Content file model with attributes for clean access

size_formatted `property`

size_formatted: str

Get formatted file size

to_dict

to_dict() -> Dict[str, Any]

Convert back to dictionary format

User Profile

robutler.api.client.UserProfile

User profile model with attributes for clean access

to_dict

to_dict() -> Dict[str, Any]

Convert back to dictionary format

Exceptions

robutler.api.client.RobutlerAPIError

Bases: Exception

Exception raised when Robutler API returns an error.

This exception provides detailed information about API failures including HTTP status codes and response data for debugging.

Attributes:

Name	Type	Description
`message`		Human-readable error message
`status_code`		HTTP status code from the API response
`response_data`		Raw response data from the API

Example

try:
    user = await client.user.get()
except RobutlerAPIError as e:
    print(f"API Error: {e} (Status: {e.status_code})")
    print(f"Response: {e.response_data}")

Practical Examples

User Account Management

async def get_account_summary():
    """Get a complete account summary with user info, credits, and recent activity."""
    async with RobutlerClient() as client:
        # Get user profile (single call, typed object)
        user = await client.user.get()

        # Get current credit balance
        credits = await client.user.credits()

        # Get recent transaction history
        transactions = await client.user.transactions(limit=10)

        # Get API keys
        api_keys = await client.api_keys.list()

        return {
            "user": {
                "name": user.name,
                "email": user.email,
                "plan": user.plan_name,
                "credits": str(credits)
            },
            "recent_transactions": len(transactions),
            "api_keys": len(api_keys)
        }

Agent Operations

async def create_and_configure_agent():
    """Create a new agent and configure its settings."""
    async with RobutlerClient() as client:
        # Create new agent
        agent = await client.agents.create({
            "name": "data-analyst",
            "instructions": "You are a data analysis expert. Help users understand their data through clear visualizations and insights.",
            "model": "gpt-4o",
            "description": "Specialized in data analysis and visualization",
            "isPublic": True,
            "canTalkToOtherAgents": True
        })

        print(f"Created agent: {agent.name} (ID: {agent.id})")

        # Get the agent's API key for external integrations
        agent_resource = await client.agents.get(agent.id)
        api_key = await agent_resource.api_key()

        print(f"Agent API key: {api_key}")

        return agent

Content and File Management

async def manage_content_files():
    """Upload files and manage agent access to content."""
    async with RobutlerClient() as client:
        # Upload a public file that agents can access
        with open("dataset.csv", "rb") as f:
            public_file = await client.content.upload(
                file_data=f.read(),
                filename="dataset.csv",
                visibility="public"  # Agents can access this
            )

        # Upload a private file for user-only access
        with open("private_notes.txt", "rb") as f:
            private_file = await client.content.upload(
                file_data=f.read(),
                filename="private_notes.txt",
                visibility="private"  # User-only access
            )

        print(f"Public file: {public_file.name} ({public_file.size_formatted})")
        print(f"Private file: {private_file.name} ({private_file.size_formatted})")

        # Get all files accessible to agents
        agent_files = await client.content.agent_access()
        print(f"Agents can access {len(agent_files)} files:")
        for file in agent_files:
            print(f"  📄 {file.name} - {file.url}")

Error Handling Best Practices

async def robust_api_usage():
    """Demonstrate proper error handling with the Robutler client."""
    try:
        async with RobutlerClient() as client:
            # Attempt to get user information
            user = await client.user.get()
            print(f"Successfully authenticated as: {user.name}")

            # Attempt to list agents
            agents = await client.agents.list()
            print(f"Found {len(agents)} agents")

    except RobutlerAPIError as e:
        # Handle specific API errors
        if e.status_code == 401:
            print("Authentication failed - check your API key")
        elif e.status_code == 403:
            print("Access denied - insufficient permissions")
        elif e.status_code == 404:
            print("Resource not found")
        elif e.status_code >= 500:
            print("Server error - please try again later")
        else:
            print(f"API Error: {e} (Status: {e.status_code})")

        # Log detailed error information for debugging
        print(f"Error details: {e.response_data}")

    except Exception as e:
        # Handle unexpected errors
        print(f"Unexpected error: {e}")

Robutler Python SDK

Installation

Quick Start

Environment Configuration

API Reference

Main Client

robutler.api.client.RobutlerClient

agents instance-attribute

content instance-attribute

user instance-attribute

api_keys instance-attribute

tokens instance-attribute

intents instance-attribute

__init__

close async

Resources

Agent Management

robutler.api.client.AgentsResource

list async

get_by_name async

get_by_id async

get async

create async

update async

delete async

search async

discover async

find_similar async

Content Management

robutler.api.client.ContentResource

agent_access async

list async

upload async

delete async

User Management

robutler.api.client.UserResource

get async

credits async

transactions async

Model Objects

Agent

robutler.api.client.Agent

to_dict

get_full_data

Content File

robutler.api.client.ContentFile

size_formatted property

to_dict

User Profile

robutler.api.client.UserProfile

to_dict

Exceptions

robutler.api.client.RobutlerAPIError

Practical Examples

User Account Management

Agent Operations

Content and File Management

Error Handling Best Practices

agents `instance-attribute`

content `instance-attribute`

user `instance-attribute`

api_keys `instance-attribute`

tokens `instance-attribute`

intents `instance-attribute`

init

close `async`

list `async`

get_by_name `async`

get_by_id `async`

get `async`

create `async`

update `async`

delete `async`

search `async`

discover `async`

find_similar `async`

agent_access `async`

list `async`

upload `async`

delete `async`

get `async`

credits `async`

transactions `async`

size_formatted `property`