Python Package: Functions

Below are the core functionalities you'll use when working with our Python client library. You can interact with your agents in two main ways:

1. Using the Agent class – for object-oriented messaging, file uploads, and streaming.
2. Using legacy standalone functions – for functional style and backward compatibility.

The Agent class provides a convenient interface for all operations:

• message(text, **kwargs): Send a text message to the agent
• upload_file(file_path, file_obj): Upload a file to the agent
• start_streaming(callback, use_persistent): Start WebSocket streaming
• stop_streaming(): Stop WebSocket streaming
• stop_agent(message, reason): Send a stop signal to the agent

Each method returns the API response, which usually includes WebSocket URLs and session IDs.

PYTHON
Copy
from agent_client import Agent

API_KEY = "YOUR_API_KEY"
AGENT_ID = "YOUR_AGENT_ID"

# Create an Agent instance
agent = Agent(
    agent_id=AGENT_ID,
    api_key=API_KEY,
    base_url="https://api.levangielaboratories.com"
)

# Send a message
response = agent.message("Hello, Agent!")
print("Response:", response)

# Send message with additional parameters
response = agent.message("Tell me about this code", code="print('hello world')")

# Upload a file
with open("my_local_file.txt", "rb") as f:
    upload_resp = agent.upload_file("agent_data/file.txt", f)
    print("Upload response:", upload_resp)

# Stream responses in the background
def handle_streamed_data(data):
    print("Stream received:", data)

agent.start_streaming(callback=handle_streamed_data)

# Do something else while streaming...

# When finished, stop streaming:
agent.stop_streaming()

# Stop the agent when done
agent.stop_agent(message="Task completed", reason="User finished interaction")

For compatibility with older code, the package provides these standalone functions:

• send_operation(agent_id, api_key, operation, params, base_url): Send any operation
• upload_file(agent_id, api_key, file_path, file_obj, base_url): Upload a file
• connect_websocket(ws_url, callback): Async function to connect to WebSocket
• stream_websocket(ws_url, callback): Start WebSocket streaming in a thread

PYTHON
Copy
from agent_client import send_operation, upload_file, stream_websocket

API_KEY = "YOUR_API_KEY"
AGENT_ID = "YOUR_AGENT_ID"
BASE_URL = "https://api.levangielaboratories.com"

# Send a message operation
resp = send_operation(
    agent_id=AGENT_ID,
    api_key=API_KEY,
    operation="message",
    params={"message": "Hello via operation!"},
    base_url=BASE_URL
)
print("Operation response:", resp)

# Upload a file
with open("./localfile.txt", "rb") as f:
    up_resp = upload_file(
        agent_id=AGENT_ID,
        api_key=API_KEY,
        file_path="/agent_data/uploaded.txt",
        file_obj=f,
        base_url=BASE_URL
    )
print("Upload file response:", up_resp)

# Stream from WebSocket URL (obtained from response)
ws_url = resp.get("persistent_ws_url")

def handle_ws_message(data):
    print("WebSocket data:", data)

# Start streaming in background thread
thread = stream_websocket(ws_url, handle_ws_message)

# Thread runs in background until program exits

When streaming, your callback function will receive JSON objects from the agent. These may include different types of messages:

• Regular text responses
• Status updates
• Error messages
• Results or data objects

Your callback should handle the different message formats appropriately:

PYTHON
Copy
def handle_stream(data):
    # Check for different message types
    if "type" in data:
        msg_type = data["type"]
        if msg_type == "error":
            print(f"ERROR: {data.get('content')}")
        elif msg_type == "info" or msg_type == "status":
            print(f"INFO: {data.get('content')}")
        elif msg_type == "result" or msg_type == "data":
            print(f"RESULT: {data}")
    elif "message" in data:
        print(f"MESSAGE: {data['message']}")
    elif "content" in data:
        print(f"CONTENT: {data['content']}")
    else:
        print(f"OTHER: {data}")