Error Handling & Operations

Error Handling & Operations

← Back to home

Auto-Reconnect Mechanism

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

FeatureBehavior
Connection lostAuto-reconnect with 3-second delay (via threading.Timer)
Retry countInfinite retries (until release() is called)
HeartbeatBuilt into websocket-client; Ping every 10 seconds (ping_interval=10s, ping_timeout=5s)
SignatureComputed on the fly from app_key / app_secret (HMAC-SHA256) on each auth; no token expiry
After reconnectionThe 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 == 5:
            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

Error code ranges are partitioned by responsible system (which system produced the code). Integrators should branch on code, not parse the errorMsg text. See dep/AgentErrorCode错误码规范.md for the full contract.

RangeResponsible systemExamples
0SuccessAuth success, request ack success
1-999AgentSdk itself (never touches network)Connection already closed, payload validation failure
1000-1999二开网关 (linksoul-linksky)1001=Token expired, 1004=Signature error, 1003=Robot offline
2000-2999交互网关 (aiem-emp)Session/scheduler not found
3000-3999Robot sideRobot execution failed
4000-4900Integrator-defined business errorsDeveloper-defined, values not specified by the SDK

Resource Release

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

release() performs the following:

  1. Sets the released flag, stops auto-reconnect
  2. Closes the WebSocket connection (linksky_client.stop())
  3. Cleans up callbackType / agentId / agentMeta registrations
  4. Cleans up TaskFlow / Teleop / ExtSkill / Response caches by client reference
  5. 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

SymptomPossible CauseHow to Investigate
Auth failed code=1004Wrong app_key / app_secret, or signature payload mismatchVerify app_key / app_secret; signature payload must be "GET\n{path}\n{timestamp}\n{nonce}"
Connected but no messages receivedCallback registered after initialize()Ensure callbacks are registered before initialization
on_request not being calledRobot not online or callbackType mismatchCheck whether on_robot_online fires
Response method calls have no effectResponse already cleaned up (120s timeout)Ensure processing takes less than 120 seconds
Memory keeps growingrelease() not called or many agentIds not going offlineCheck robot lifecycle management