Skip to navigation
ResourcesSDK's

Swift SDK

ElevenAgents SDK: implementeer aangepaste, interactieve spraakagenten in je Swift-applicaties.

Bekijk ons volledige Swift-quickstartproject om snel aan de slag te gaan met een volledig werkend voorbeeld.

Installatie

Voeg de ElevenLabs Swift SDK toe aan je project met Swift Package Manager:

1

Pakketafhankelijkheid toevoegen

dependencies: [ .package(url: "https://github.com/elevenlabs/elevenlabs-swift-sdk.git",
from: "2.0.0") ]

Of met Xcode:

  1. Open je project in Xcode
  2. Ga naar File > Add Package Dependencies...
  3. Voer de repository-URL in: https://github.com/elevenlabs/elevenlabs-swift-sdk.git
  4. Selecteer versie 2.0.0 of hoger
2

SDK importeren

import ElevenLabs

Zorg dat je NSMicrophoneUsageDescription toevoegt aan je Info.plist om gebruikers uit te leggen waarom microfoontoegang nodig is. De SDK vereist iOS 14.0+ / macOS 11.0+ en Swift 5.9+.

Snelstart

Begin met een eenvoudig gesprek in slechts enkele regels. Optioneel raden we aan je eigen eindgebruikers-ID’s door te geven om gesprekken aan je gebruikers te koppelen.

import ElevenLabs
// Start a conversation with your agent
let conversation = try await ElevenLabs.startConversation(
    agentId: "your-agent-id",
    userId: "your-end-user-id",
    config: ConversationConfig()
)
// Observe conversation state and messages
conversation.$state
    .sink { state in
        print("Connection state: \(state)")
    }
    .store(in: &cancellables)
conversation.$messages
    .sink { messages in
        for message in messages {
            print("\(message.role): \(message.content)")
        }
    }
    .store(in: &cancellables)
// Send messages and control the conversation
try await conversation.sendMessage("Hello!")
try await conversation.toggleMute()
await conversation.endConversation()

Authenticatie

Er zijn twee manieren om te authenticeren en een gesprek te starten:

Gebruik voor public agents rechtstreeks de agent-ID:

let conversation = try await ElevenLabs.startConversation(
    agentId: "your-public-agent-id",
    config: ConversationConfig()
)

Kernfuncties

Reactief gespreksbeheer

De SDK biedt een moderne klasse Conversation met @Published-properties voor reactieve UI-updates:

@MainActor
class ConversationManager: ObservableObject {
    @Published var conversation: Conversation?
    private var cancellables = Set<AnyCancellable>()
    func startConversation(agentId: String) async throws {
        let config = ConversationConfig(
            conversationOverrides: ConversationOverrides(textOnly: false)
        )
        conversation = try await ElevenLabs.startConversation(
            agentId: agentId,
            config: config
        )
        setupObservers()
    }
    private func setupObservers() {
        guard let conversation else { return }
        // Monitor connection state
        conversation.$state
            .sink { state in print("State: \(state)") }
            .store(in: &cancellables)
        // Monitor messages
        conversation.$messages
            .sink { messages in print("Messages: \(messages.count)") }
            .store(in: &cancellables)
    }
}

Spraak- en tekstmodi

// Voice conversation (default)
let voiceConfig = ConversationConfig(
    conversationOverrides: ConversationOverrides(textOnly: false)
)
// Text-only conversation
let textConfig = ConversationConfig(
    conversationOverrides: ConversationOverrides(textOnly: true)
)

Audiobediening

// Microphone control
try await conversation.toggleMute()
try await conversation.setMuted(true)
// Check microphone state
let isMuted = conversation.isMuted
// Access audio tracks for advanced use cases
let inputTrack = conversation.inputTrack
let agentAudioTrack = conversation.agentAudioTrack

Client tools

Met client tools kun je aangepaste functies registreren die je AI-agent tijdens gesprekken kan aanroepen. De nieuwe SDK biedt verbeterde parameterverwerking en foutbeheer.

Toolaanroepen afhandelen

Handel toolaanroepen van je agent af met volledige parameterondersteuning:

private func handleToolCall(_ toolCall: ClientToolCallEvent) async {
    do {
        let parameters = try toolCall.getParameters()
        let result = await executeClientTool(
            name: toolCall.toolName,
            parameters: parameters
        )
        if toolCall.expectsResponse {
            try await conversation?.sendToolResult(
                for: toolCall.toolCallId,
                result: result
            )
        } else {
            conversation?.markToolCallCompleted(toolCall.toolCallId)
        }
    } catch {
        // Handle tool execution errors
        if toolCall.expectsResponse {
            try? await conversation?.sendToolResult(
                for: toolCall.toolCallId,
                result: ["error": error.localizedDescription],
                isError: true
            )
        }
    }
}
// Example tool implementation
func executeClientTool(name: String, parameters: [String: Any]) async -> [String: Any] {
    switch name {
    case "get_weather":
        guard let location = parameters["location"] as? String else {
            return ["error": "Missing location parameter"]
        }
        // Fetch weather data
        return ["temperature": "22°C", "condition": "Sunny"]
    case "send_email":
        guard let recipient = parameters["recipient"] as? String,
              let subject = parameters["subject"] as? String else {
            return ["error": "Missing required parameters"]
        }
        // Send email logic
        return ["status": "sent", "messageId": "12345"]
    default:
        return ["error": "Unknown tool: \(name)"]
    }
}

Vergeet niet je agent in te stellen met de client tools in de ElevenLabs UI. Bekijk de documentatie over client tools voor instructies.

Verbindingsstatus beheren

Monitor de gespreksstatus om verschillende verbindingsfasen af te handelen:

conversation.$state
    .sink { state in
        switch state {
        case .idle:
            // Not connected
            break
        case .connecting:
            // Show connecting indicator
            break
        case .active(let callInfo):
            // Connected to agent: \(callInfo.agentId)
            break
        case .ended(let reason):
            // Handle disconnection: \(reason)
            break
        case .error(let error):
            // Handle error: \(error)
            break
        }
    }
    .store(in: &cancellables)

Agentstatus monitoren

Houd bij wanneer de agent luistert of spreekt:

conversation.$agentState
    .sink { state in
        switch state {
        case .listening:
            // Agent is listening, show listening indicator
            break
        case .speaking:
            // Agent is speaking, show speaking indicator
            break
        }
    }
    .store(in: &cancellables)

Berichten afhandelen

Stuur tekstberichten en monitor het gesprek:

// Send a text message
try await conversation.sendMessage("Hello, how can you help me today?")
// Monitor all messages in the conversation
conversation.$messages
    .sink { messages in
        for message in messages {
            switch message.role {
            case .user:
                print("User: \(message.content)")
            case .agent:
                print("Agent: \(message.content)")
            }
        }
    }
    .store(in: &cancellables)

Audio-uitlijning

Monitor timinggegevens per teken voor synchrone tekstweergave:

// Using the callback
let config = ConversationConfig(
    onAudioAlignment: { alignment in
        // Character-level timing data
        for (index, char) in alignment.chars.enumerated() {
            let startMs = alignment.charStartTimesMs[index]
            let durationMs = alignment.charDurationsMs[index]
            print("'\(char)' at \(startMs)ms for \(durationMs)ms")
        }
    }
)
// Or observe the published property
conversation.$latestAudioAlignment
    .compactMap { $0 }
    .sink { alignment in
        // Handle alignment updates
    }
    .store(in: &cancellables)

Sessiebeheer

// End the conversation
await conversation.endConversation()
// Check if conversation is active
let isActive = conversation.state.isActive

SwiftUI-integratie

Hier is een uitgebreid SwiftUI-voorbeeld met de nieuwe SDK:

import SwiftUI
import ElevenLabs
import Combine
struct ConversationView: View {
    @StateObject private var viewModel = ConversationViewModel()
    var body: some View {
        VStack(spacing: 20) {
            // Connection status
            Text(viewModel.connectionStatus)
                .font(.headline)
                .foregroundColor(viewModel.isConnected ? .green : .red)
            // Chat messages
            ScrollView {
                LazyVStack(alignment: .leading, spacing: 8) {
                    ForEach(viewModel.messages, id: \.id) { message in
                        MessageBubble(message: message)
                    }
                }
            }
            .frame(maxHeight: 400)
            // Controls
            HStack(spacing: 16) {
                Button(viewModel.isConnected ? "End" : "Start") {
                    Task {
                        if viewModel.isConnected {
                            await viewModel.endConversation()
                        } else {
                            await viewModel.startConversation()
                        }
                    }
                }
                .buttonStyle(.borderedProminent)
                Button(viewModel.isMuted ? "Unmute" : "Mute") {
                    Task { await viewModel.toggleMute() }
                }
                .buttonStyle(.bordered)
                .disabled(!viewModel.isConnected)
                Button("Send Message") {
                    Task { await viewModel.sendTestMessage() }
                }
                .buttonStyle(.bordered)
                .disabled(!viewModel.isConnected)
            }
            // Agent state indicator
            if viewModel.isConnected {
                HStack {
                    Circle()
                        .fill(viewModel.agentState == .speaking ? .blue : .gray)
                        .frame(width: 10, height: 10)
                    Text(viewModel.agentState == .speaking ? "Agent speaking" : "Agent listening")
                        .font(.caption)
                }
            }
        }
        .padding()
    }
}
struct MessageBubble: View {
    let message: Message
    var body: some View {
        HStack {
            if message.role == .user { Spacer() }
            VStack(alignment: .leading) {
                Text(message.role == .user ? "You" : "Agent")
                    .font(.caption)
                    .foregroundColor(.secondary)
                Text(message.content)
                    .padding()
                    .background(message.role == .user ? Color.blue : Color.gray.opacity(0.3))
                    .foregroundColor(message.role == .user ? .white : .primary)
                    .cornerRadius(12)
            }
            if message.role == .agent { Spacer() }
        }
    }
}
@MainActor
class ConversationViewModel: ObservableObject {
    @Published var messages: [Message] = []
    @Published var isConnected = false
    @Published var isMuted = false
    @Published var agentState: AgentState = .listening
    @Published var connectionStatus = "Disconnected"
    private var conversation: Conversation?
    private var cancellables = Set<AnyCancellable>()
    func startConversation() async {
        do {
            conversation = try await ElevenLabs.startConversation(
                agentId: "your-agent-id",
                config: ConversationConfig()
            )
            setupObservers()
        } catch {
            print("Failed to start conversation: \(error)")
            connectionStatus = "Failed to connect"
        }
    }
    func endConversation() async {
        await conversation?.endConversation()
        conversation = nil
        cancellables.removeAll()
    }
    func toggleMute() async {
        try? await conversation?.toggleMute()
    }
    func sendTestMessage() async {
        try? await conversation?.sendMessage("Hello from the app!")
    }
    private func setupObservers() {
        guard let conversation else { return }
        conversation.$messages
            .assign(to: &$messages)
        conversation.$state
            .map { state in
                switch state {
                case .idle: return "Disconnected"
                case .connecting: return "Connecting..."
                case .active: return "Connected"
                case .ended: return "Ended"
                case .error: return "Error"
                }
            }
            .assign(to: &$connectionStatus)
        conversation.$state
            .map { $0.isActive }
            .assign(to: &$isConnected)
        conversation.$isMuted
            .assign(to: &$isMuted)
        conversation.$agentState
            .assign(to: &$agentState)
    }
}