SwiftAnthropic

Skills are tools that extend Claude's capabilities (e.g., spreadsheet manipulation via xlsx). To use a skill in a message, you must:

1. Include code execution tools in the tools parameter.
2. Reference the skill within a container object.

Containers allow you to maintain state across multiple turns. When you make a request using a skill, the response may include a container.id. For better performance in multi-turn conversations, pass this id back in the container parameter of your subsequent requests. This allows Claude to reuse the same execution environment.

// Example of a message using a skill and code execution tools
let parameters = MessageParameter(
    model: .claude37Sonnet,
    messages: [userMessage],
    maxTokens: 4096,
    tools: [.hosted(type: "code_execution_20250825", name: "code_execution")],
    container: .init(
        id: nil, // Use nil for the first request; reuse an existing ID for subsequent turns
        skills: [
            .init(type: .anthropic, skillId: "xlsx", version: "latest")
        ]
    )
)

Prompt Caching (in public beta) allows you to reduce costs and latency by caching large context blocks. To use it, ensure your request includes the prompt-caching-2024-07-31 beta header. In SwiftAnthropic, you apply caching using .init(type: .ephemeral) on various components:

• System Prompts: Use MessageParameter.Cache within the system parameter.
• Messages: Use MessageParameter.Message.Content.ContentObject.cache within a message's content list.
• Tools: Use cacheControl on a MessageParameter.Tool definition.
• Documents: Use cacheControl on the MessageParameter.Message.Content.DocumentSource.pdf object.
• Tool Results: Use cacheControl on the toolResult content object.

// Example: Caching a large document
let pdfData = // your PDF data
let base64PDF = pdfData.base64EncodedString()

let documentSource = try MessageParameter.Message.Content.DocumentSource.pdf(
    base64Data: base64PDF,
    title: "Large Research Document",
    cacheControl: .init(type: .ephemeral)
)

let message = MessageParameter.Message(
    role: .user,
    content: .list([
        .document(documentSource),
        .text("Please analyze this document")
    ])
)

let parameters = MessageParameter(
    model: .claude35Sonnet,
    messages: [message],
    maxTokens: 1024
)

let response = try await service.createMessage(parameters)

Claude can interact with external tools by providing a tools array in the MessageParameter.

When Claude decides to use a tool, the MessageResponse will have a stop_reason of tool_use and a content block of type tool_use. This block includes:

• id: A unique identifier to match tool results later.
• name: The name of the tool being called.
• input: An object containing the arguments for the tool.

Disabling Parallel Tool Use

By default, Claude may use multiple tools. To restrict Claude to at most one tool (when type is .auto) or exactly one tool (when type is .any or .tool), set disableParallelToolUse: true in the ToolChoice object.

let maxTokens = 1024
let weatherTool = MessageParameter.Tool.function(
    name: "get_weather", 
    description: "Get the current weather in a given location",
    inputSchema: .init(
        type: .object,
        properties: [
            "location": .init(type: .string, description: "The city and state, e.g. San Francisco, CA"),
            "unit": .init(type: .string, description: "The unit of temperature, either celsius or fahrenheit")
        ],
        required: ["location"]
    )
)

let messageParameter = MessageParameter.Message(role: .user, content: "What is the weather like in San Francisco?")
let parameters = MessageParameter(model: .claude3Opus, messages: [messageParameter], maxTokens: maxTokens, tools: [weatherTool])

let message = try await service.createMessage(parameters)

// To disable parallel tool use:
let toolChoice = ToolChoice(type: .auto, disableParallelToolUse: true)
let parametersWithLimitedTools = MessageParameter(
    model: model,
    messages: messages,
    maxTokens: maxTokens,
    toolChoice: toolChoice
)

The Text Editor Tool allows Claude to view and modify files directly. This is a hosted tool and is only compatible with specific models:

• Claude 3.7 Sonnet: Use text_editor_20250124
• Claude 3.5 Sonnet: Use text_editor_20241022

Available Commands

When processing the tool_use content block, you must implement the following commands from the input object:

1. view: Examine file contents. Requires path and optional view_range.
2. str_replace: Replace text. Requires path, old_str, and new_str.
3. create: Create a new file. Requires path and file_text.
4. insert: Insert text at a location. Requires path, insert_line, and new_str.
5. undo_edit: Revert the last edit. Requires path.

// Define the text editor tool
let textEditorTool = MessageParameter.Tool.hosted(
    type: "text_editor_20250124", // Match version to model
    name: "str_replace_editor"
)

let messageParameter = MessageParameter.Message(role: .user, content: .text("There's a syntax error in my primes.py file. Can you help fix it?"))

let parameters = MessageParameter(
    model: .claude37Sonnet, 
    messages: [messageParameter], 
    maxTokens: 1024,
    tools: [textEditorTool]
)

let message = try await service.createMessage(parameters)

// Handle the tool use response
for content in message.content {
    if case .toolUse(let id, let name, let input) = content {
        if let command = input["command"]?.stringValue {
            switch command {
            case "view":
                // Implement file reading logic
            case "str_replace":
                // Implement text replacement logic
            case "create":
                // Implement file creation logic
            case "insert":
                // Implement text insertion logic
            case "undo_edit":
                // Implement undo logic
            default:
                break
            }
        }
    }
}