Consume generated attributes (#743)

- Adds generated attributes
https://github.com/livekit/attribute-definitions
- Consumes agent attributes via `Participant.State` (cache)
- Transcription attributes will come soon with moving the logic from the
VoiceAgent → SDK

A basic test case:
- See if the agent (visualizer) state is handled properly
- Avatars are also fine
- You may need livekit/components-swift#27

Author: pblazej

Sources/LiveKit/Agent/AgentState+.swift

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+extension AgentState: CustomStringConvertible {
+    public var description: String {
+        rawValue.capitalized
+    }
+}

Sources/LiveKit/Agent/AgentState.swift

@@ -25,19 +25,20 @@ public extension Participant {
         }
     }
 
-    @objc
     var agentState: AgentState {
-        guard isAgent else { return .unknown }
-        guard let attrString = attributes[agentStateAttributeKey] else { return .unknown }
-        guard let state = AgentState.fromString(attrString) else { return .unknown }
-        return state
+        _state.agentAttributes?.lkAgentState ?? .idle
+    }
+
+    @objc
+    var agentStateString: String {
+        agentState.rawValue
     }
 }
 
 public extension Participant {
     private var publishingOnBehalf: [Participant.Identity: Participant] {
         guard let _room else { return [:] }
-        return _room.allParticipants.filter { $0.value.attributes[publishOnBehalfAttributeKey] == identity?.stringValue }
+        return _room.allParticipants.filter { $0.value._state.agentAttributes?.lkPublishOnBehalf == identity?.stringValue }
     }
 
     /// The avatar worker participant associated with the agent.

Sources/LiveKit/Agent/Participant+Agent.swift

@@ -16,16 +16,14 @@
 
 import Foundation
 
-let publishOnBehalfAttributeKey = "lk.publish_on_behalf"
-
 public extension Room {
     /// A dictionary containing all agent participants.
     ///
     /// - Note: This will not include participants that are publishing on behalf of another participant
     /// e.g. avatar workers. To access them directly use ``Participant/avatarWorker`` property of `agentParticipant`.
     @objc
     var agentParticipants: [Participant.Identity: Participant] {
-        allParticipants.filter { $0.value.isAgent && $0.value.attributes[publishOnBehalfAttributeKey] == nil }
+        allParticipants.filter { $0.value.isAgent && $0.value._state.agentAttributes?.lkPublishOnBehalf == nil }
     }
 
     /// The first agent participant.

Sources/LiveKit/Agent/Room+Agent.swift

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Foundation
+
+extension Encodable {
+    func mapped<T: Decodable>(to type: T.Type,
+                              encoder: JSONEncoder = JSONEncoder(),
+                              decoder: JSONDecoder = JSONDecoder()) -> T?
+    {
+        guard let encoded = try? encoder.encode(self),
+              let decoded = try? decoder.decode(type, from: encoded) else { return nil }
+
+        return decoded
+    }
+}

Sources/LiveKit/Extensions/Codable.swift

@@ -95,6 +95,7 @@ public class Participant: NSObject, @unchecked Sendable, ObservableObject, Logga
         var permissions = ParticipantPermissions()
         var trackPublications = [Track.Sid: TrackPublication]()
         var attributes = [String: String]()
+        var agentAttributes: AgentAttributes?
     }
 
     struct InternalState: Equatable, Hashable {
@@ -241,6 +242,7 @@ public class Participant: NSObject, @unchecked Sendable, ObservableObject, Logga
             $0.metadata = info.metadata
             $0.kind = info.kind.toLKType()
             $0.attributes = info.attributes
+            $0.agentAttributes = info.attributes.mapped(to: AgentAttributes.self)
             $0.state = info.state.toLKType()
 
             // Attempt to get millisecond precision.

Sources/LiveKit/Participant/Participant.swift

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2025 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import Foundation
+
+// Quicktype cannot generate both at the same time
+extension AgentAttributes: Hashable {}
+extension AgentAttributes: Equatable {}
+
+// MARK: - AgentAttributes
+
+struct AgentAttributes: Codable, Sendable {
+    let lkAgentInputs: [AgentInput]?
+    let lkAgentOutputs: [AgentOutput]?
+    let lkAgentState: AgentState?
+    let lkPublishOnBehalf: String?
+
+    enum CodingKeys: String, CodingKey {
+        case lkAgentInputs = "lk.agent.inputs"
+        case lkAgentOutputs = "lk.agent.outputs"
+        case lkAgentState = "lk.agent.state"
+        case lkPublishOnBehalf = "lk.publish_on_behalf"
+    }
+}
+
+enum AgentInput: String, Codable, Sendable {
+    case audio
+    case text
+    case video
+}
+
+enum AgentOutput: String, Codable, Sendable {
+    case audio
+    case transcription
+}
+
+public enum AgentState: String, Codable, Sendable {
+    case idle
+    case initializing
+    case listening
+    case speaking
+    case thinking
+}
+
+/// Schema for transcription-related attributes
+
+// MARK: - TranscriptionAttributes
+
+struct TranscriptionAttributes: Codable, Sendable {
+    /// The segment id of the transcription
+    let lkSegmentID: String?
+    /// The associated track id of the transcription
+    let lkTranscribedTrackID: String?
+    /// Whether the transcription is final
+    let lkTranscriptionFinal: Bool?
+
+    enum CodingKeys: String, CodingKey {
+        case lkSegmentID = "lk.segment_id"
+        case lkTranscribedTrackID = "lk.transcribed_track_id"
+        case lkTranscriptionFinal = "lk.transcription_final"
+    }
+}