Error Handling & Operations

← Back to home

Auto-Reconnect Mechanism

The SDK has built-in auto-reconnect; no developer handling is needed:

Feature	Behavior
Connection lost	Auto-reconnect with 3-second delay (via `threading.Timer`)
Retry count	Infinite retries (until `release()` is called)
Heartbeat	Built into `websocket-client`; Ping every 10 seconds (`ping_interval=10s, ping_timeout=5s`)
Signature	Computed on the fly from `app_key` / `app_secret` (HMAC-SHA256) on each auth; no token expiry
After reconnection	The robot resends online events

Auth Callback

python

from linksoul_agentsdk import AgentAuthCallback


class MyAuth(AgentAuthCallback):
    def on_auth_state(self, app_id: str, code: int, msg: str) -> None:
        if code == 0:
            print("Authentication successful")
        elif code == 1001:
            print("Token expired (should not occur)")
        elif code == 1004:
            print("Signature verification failed, check app_key / app_secret")
        elif code == 1005:
            print("WebSocket handshake failed")
        else:
            print(f"Authentication error: code={code}, msg={msg}")


agent_sdk.register_auth(MyAuth())

Returning Business Errors via Response

When SDK-side processing fails, notify the robot via response.on_error():

python

def on_request(self, agent_id, event_id, flag, buf, param, response):
    try:
        # Business processing...
        pass
    except Exception as e:
        response.on_error(event_id, 5001, f"ASR service timeout: {e}")

Error Code Conventions

Range	Meaning	Examples
0	Success	Authentication success, request acknowledgment success
1000-1999	Authentication/connection errors	1001=Token expired, 1004=Signature error
2000-2999	Protocol errors	Message format error
3000-3999	Gateway errors	Routing failure
4000-4999	Robot-side errors	Robot not online
5000-5999	SDK-side business errors	Developer-defined errors

Resource Release

python

# Release the SDK instance (disconnect, clean up all registered callbacks and caches)
agent_sdk.release()

release() performs the following:

Sets the released flag, stops auto-reconnect
Closes the WebSocket connection (linksky_client.stop())
Cleans up callbackType / agentId / agentMeta registrations
Cleans up TaskFlow / Teleop / ExtSkill / Response caches by client reference
Shuts down this instance's worker thread pool

Note: After release(), you can call AgentSdk.create() again with the same appId to obtain a new instance.

Logging Configuration

The SDK uses the standard-library logging module, rooted at the linksoul_agentsdk logger:

python

import logging

# Normal operation
logging.getLogger("linksoul_agentsdk").setLevel(logging.INFO)

# Debug message sending/receiving and thread pool
logging.getLogger("linksoul_agentsdk.client").setLevel(logging.DEBUG)
logging.getLogger("linksoul_agentsdk.mgr").setLevel(logging.DEBUG)

Troubleshooting

Symptom	Possible Cause	How to Investigate
Auth failed code=1004	Wrong app_key / app_secret, or signature payload mismatch	Verify app_key / app_secret; signature payload must be `"GET\n{path}\n{timestamp}\n{nonce}"`
Connected but no messages received	Callback registered after initialize()	Ensure callbacks are registered before initialization
`on_request` not being called	Robot not online or callbackType mismatch	Check whether `on_robot_online` fires
Response method calls have no effect	Response already cleaned up (120s timeout)	Ensure processing takes less than 120 seconds
Memory keeps growing	release() not called or many agentIds not going offline	Check robot lifecycle management