Remote method calls (RPC)
使用 RPC 對房間中的其他參與者執行自訂方法並等待回應。
Overview
使用 RPC，您的應用程式可以在一個參與者上定義方法，該方法可以被房間內的其他參與者遠端調用，並可能返回回應。此功能可用於請求資料、協調特定於應用程式的狀態等。當用於從 AI 代理程式 forward tool calls 時，您的 LLM 可以直接存取資料或操作應用程式前端的 UI。
Method registration
首先使用 localParticipant.registerRpcMethod 在目標參與者處註冊該方法，並提供方法的名稱和處理程序函數。單一參與者可以註冊任意數量的方法。
@room.local_participant.register_rpc_method("greet")
async def handle_greet(data: RpcInvocationData):
print(f"Received greeting from {data.caller_identity}: {data.payload}")
return f"Hello, {data.caller_identity}!"
localParticipant.registerRpcMethod(
'greet',
async (data: RpcInvocationData) => {
console.log(`Received greeting from ${data.callerIdentity}: ${data.payload}`);
return `Hello, ${data.callerIdentity}!`;
}
);
localParticipant.registerRpcMethod(
'greet',
async (data: RpcInvocationData) => {
console.log(`Received greeting from ${data.callerIdentity}: ${data.payload}`);
return `Hello, ${data.callerIdentity}!`;
}
);
room.local_participant().register_rpc_method(
"greet".to_string(),
|data| {
Box::pin(async move {
println!(
"Received greeting from {}: {}",
data.caller_identity,
data.payload
);
return Ok("Hello, ".to_string() + &data.caller_identity);
})
},
);
localParticipant.registerRpcMethod(
"greet"
) { data ->
println("Received greeting from ${data.callerIdentity}: ${data.payload}")
"Hello, ${data.callerIdentity}!"
}
localParticipant.registerRpcMethod("greet") { data in
print("Received greeting from \(data.callerIdentity): \(data.payload)")
return "Hello, \(data.callerIdentity)!"
}
greetHandler := func(data livekit.RpcInvocationData) (string, error) {
fmt.Printf("Received greeting from %s: %s\n", data.CallerIdentity, data.Payload)
return "Hello, " + data.CallerIdentity + "!", nil
}
room.LocalParticipant.RegisterRpcMethod("greet", greetHandler)
Method invocation
使用 localParticipant.performRpc 透過提供目標參與者的身分、方法名稱和有效負載來呼叫遠端參與者上已註冊的 RPC 方法。這是一個傳回字串的非同步操作，並且可能會引發錯誤。
try:
response = await room.local_participant.perform_rpc(
destination_identity='recipient-identity',
method='greet',
payload='Hello from RPC!'
)
print(f"RPC response: {response}")
except Exception as e:
print(f"RPC call failed: {e}")
try {
const response = await localParticipant.performRpc({
destinationIdentity: 'recipient-identity',
method: 'greet',
payload: 'Hello from RPC!',
});
console.log('RPC response:', response);
} catch (error) {
console.error('RPC call failed:', error);
}
try {
const response = await localParticipant.performRpc({
destinationIdentity: 'recipient-identity',
method: 'greet',
payload: 'Hello from RPC!',
});
console.log('RPC response:', response);
} catch (error) {
console.error('RPC call failed:', error);
}
match room
.local_participant()
.perform_rpc(PerformRpcParams {
destination_identity: "recipient-identity".to_string(),
method: "greet".to_string(),
payload: "Hello from RPC!".to_string(),
..Default::default()
})
.await
{
Ok(response) => {
println!("RPC response: {}", response);
}
Err(e) => log::error!("RPC call failed: {:?}", e),
}
try {
val response = localParticipant.performRpc(
destinationIdentity = "recipient-identity",
method = "greet",
payload = "Hello from RPC!"
).await()
println("RPC response: $response")
} catch (e: RpcError) {
println("RPC call failed: $e")
}
do {
let response = try await localParticipant.performRpc(
destinationIdentity: "recipient-identity",
method: "greet",
payload: "Hello from RPC!"
)
print("RPC response: \(response)")
} catch let error as RpcError {
print("RPC call failed: \(error)")
}
res, err := room.LocalParticipant.PerformRpc(livekit.PerformRpcParams{
DestinationIdentity: "recipient-identity",
Method: "greet",
Payload: "Hello from RPC!",
})
if err != nil {
fmt.Printf("RPC call failed: %v\n", err)
}
fmt.Printf("RPC response: %s\n", res)
Method names
方法名稱可以是任何字串，最長為 64 個位元組（UTF-8）。
RPC 請求和回應都支援字串有效負載，最大大小為 15KiB（UTF-8）。您可以使用任何有意義的格式，例如 JSON 或 base64 編碼資料。
Response timeout
如果回應時間過長，performRpc 會使用逾時自動掛斷。預設逾時時間為 10 秒，但您可以在 performRpc 呼叫中根據需要隨意更改它。一般來說，您應該設定盡可能短的超時時間，同時仍然滿足您的用例。
您設定的逾時將用於整個請求持續時間，包括網路延遲。這意味著處理程序提供的超時時間將比總體超時時間短。
Errors
performRpc 將傳回某些內建錯誤（詳見下文），或您在遠端方法處理程序中產生的自訂錯誤。
若要向呼叫者傳回自訂錯誤，處理程序應拋出具有下列屬性的 RpcError 類型的錯誤：
code: 指示錯誤類型的數字。代碼 1001-1999 保留用於 LiveKit 內部錯誤。message: 提供錯誤可讀描述的字串。data: 可選字串，提供有關錯誤的更多上下文，具有與請求/回應有效負載相同的格式和限制。
處理程序中拋出的任何其他錯誤都會被捕獲，並且呼叫者將收到通用的“1500 應用程式錯誤 1500 Application Error。
Built-in error types