Llamar a Claude desde Go con el SDK oficial

anthropic-sdk-go es el cliente oficial de Go para la API de Mensajes de Claude, que proporciona a los servicios Go solicitudes tipadas, un iterador de streaming y soporte estructurado para tool_use sin necesidad de llamadas HTTP manuales.

Resumen

anthropic-sdk-go envuelve la misma API de Mensajes utilizada por todos los demás SDK oficiales de Claude, pero construida en torno a las convenciones de Go: structs de solicitud y respuesta tipadas, opciones funcionales para la configuración del cliente y errores devueltos como valores en lugar de excepciones.

Un cliente es un único objeto de larga duración que construyes una vez por proceso y reutilizas en las solicitudes, ya que contiene el transporte HTTP y la clave API.

Las tres cosas que la mayoría de los servicios Go necesitan de Claude son una llamada simple de solicitud/respuesta, una llamada de streaming para salida incremental y un bucle tool_use para permitir que Claude llame a funciones en tu servicio.

Las tres residen en la misma interfaz client.Messages, difiriendo solo en qué método llamas y cómo consumes el resultado.

Esta página cubre las tres, en el orden en que la mayoría de los servicios Go las adoptan.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

client := anthropic.NewClient(
    option.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
)
 
message, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
    Model:     anthropic.ModelClaudeSonnet5,
    MaxTokens: 1024,
    System:    anthropic.String("Eres un asistente conciso."),
    Messages: []anthropic.MessageParam{
        anthropic.NewUserMessage(anthropic.NewTextBlock("Resume el planificador de Go en dos frases.")),
    },
})
if err != nil {
    log.Fatal(err)
}
 
fmt.Println(message.Content[0].Text)

Cuándo recurrir a esto:

• Estás construyendo un servicio Go (API HTTP, CLI, trabajador en segundo plano) que necesita acceso tipado a Claude.
• Quieres comprobación en tiempo de compilación en los campos de solicitud en lugar de un cuerpo JSON crudo.
• Necesitas transmitir salida parcial a un cliente, o permitir que Claude llame a funciones en tu proceso a través de tool_use.
• Estás consolidando múltiples clientes HTTP ad hoc en una dependencia compartida y tipada.

Ejemplo de trabajo

Un único programa Go que construye un cliente, envía una solicitud de streaming e imprime tokens a medida que llegan.

package main
 
import (
    "context"
    "fmt"
    "log"
    "os"
 
    "github.com/anthropics/anthropic-sdk-go"
    "github.com/anthropics/anthropic-sdk-go/option"
)
 
func main() {
    client := anthropic.NewClient(
        option.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
    )
 
    ctx := context.Background()
 
    stream := client.Messages.NewStreaming(ctx, anthropic.MessageNewParams{
        Model:     anthropic.ModelClaudeSonnet5,
        MaxTokens: 512,
        Messages: []anthropic.MessageParam{
            anthropic.NewUserMessage(anthropic.NewTextBlock("Enumera tres beneficios de las goroutines de Go.")),
        },
    })
 
    message := anthropic.Message{}
    for stream.Next() {
        event := stream.Current()
        if err := message.Accumulate(event); err != nil {
            log.Fatal(err)
        }
 
        switch delta := event.AsAny().(type) {
        case anthropic.ContentBlockDeltaEvent:
            if textDelta, ok := delta.Delta.AsAny().(anthropic.TextDelta); ok {
                fmt.Print(textDelta.Text)
            }
        }
    }
 
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
 
    fmt.Println()
    fmt.Println("razón de parada:", message.StopReason)
}

Lo que esto demuestra:

• client.Messages.NewStreaming devuelve un iterador que controlas con stream.Next() y stream.Current(), la forma estándar de iterador de Go.
• message.Accumulate construye el Message final y completo a medida que llegan los eventos, por lo que obtienes tanto texto incremental como un objeto completo al final.
• Los deltas de texto llegan como valores ContentBlockDeltaEvent sobre los que haces un type switch, coincidiendo con la estructura de los eventos enviados por el servidor subyacentes.
• stream.Err() debe comprobarse después de que finalice el bucle, ya que un error a mitad de transmisión no necesariamente aparece dentro del propio bucle.

Inmersión Profunda

Cómo funciona

• El SDK traduce cada struct Go tipado al mismo cuerpo JSON que espera la API de Mensajes; nada sobre el formato de transmisión cambia porque estés usando Go.
• client.Messages.New emite una única solicitud HTTP bloqueante y devuelve un Message completamente poblado.
• client.Messages.NewStreaming abre una conexión de eventos enviados por el servidor y expone cada evento a través del iterador; la conexión permanece abierta hasta message_stop o un error.
• tool_use es solo otro stop_reason en la respuesta: cuando Claude decide llamar a una herramienta, el Content de la respuesta incluye un bloque tool_use en lugar de (o junto con) texto, y StopReason es "tool_use".

Uso de herramientas en Go

Definir una herramienta significa describir su esquema de entrada como un struct tipado, y luego comprobar la respuesta en busca de un bloque tool_use.

type WeatherInput struct {
    City string `json:"city"`
}
 
weatherTool := anthropic.ToolParam{
    Name:        anthropic.String("get_weather"),
    Description: anthropic.String("Obtener el clima actual de una ciudad."),
    InputSchema: anthropic.ToolInputSchemaParam{
        Type: "object",
        Properties: map[string]interface{}{
            "city": map[string]string{"type": "string"},
        },
        Required: []string{"city"},
    },
}
 
message, err := client.Messages.New(ctx, anthropic.MessageNewParams{
    Model:     anthropic.ModelClaudeSonnet5,
    MaxTokens: 512,
    Tools:     []anthropic.ToolUnionParam{{OfTool: &weatherTool}},
    Messages: []anthropic.MessageParam{
        anthropic.NewUserMessage(anthropic.NewTextBlock("¿Cuál es el clima en Denver?")),
    },
})
if err != nil {
    log.Fatal(err)
}
 
for _, block := range message.Content {
    if toolUse, ok := block.AsAny().(anthropic.ToolUseBlock); ok {
        var input WeatherInput
        if err := json.Unmarshal(toolUse.Input, &input); err != nil {
            log.Fatal(err)
        }
        fmt.Println("Claude quiere el clima para:", input.City)
        // Ejecuta tu búsqueda real aquí, luego envía un mensaje tool_result de vuelta.
    }
}

Opciones de configuración del cliente

Notas de Go

// Reutiliza un cliente en todo tu servicio; es seguro para uso concurrente.
var claudeClient = anthropic.NewClient(
    option.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
)
 
func handleRequest(ctx context.Context, prompt string) (string, error) {
    message, err := claudeClient.Messages.New(ctx, anthropic.MessageNewParams{
        Model:     anthropic.ModelClaudeSonnet5,
        MaxTokens: 1024,
        Messages: []anthropic.MessageParam{
            anthropic.NewUserMessage(anthropic.NewTextBlock(prompt)),
        },
    })
    if err != nil {
        return "", fmt.Errorf("la solicitud de claude falló: %w", err)
    }
    return message.Content[0].Text, nil
}

• El cliente es seguro para compartir entre goroutines; constrúyelo una vez al inicio y reutilízalo en las solicitudes.
• Pasa siempre un context.Context para que los tiempos de espera y la cancelación de la solicitud se propaguen correctamente bajo carga.
• Envuelve los errores con %w al devolverlos en la pila de llamadas, para que los llamadores aún puedan usar errors.As para acceder al tipo de error subyacente del SDK.

Trampas

• Construir un nuevo cliente por solicitud - crear anthropic.NewClient dentro de un manejador de solicitudes descarta el pooling de conexiones y añade latencia. Solución: construye un cliente al inicio y reutilízalo.
• Ignorar stream.Err() después del bucle - un stream que termina prematuramente debido a un error de red aún sale del bucle for stream.Next() normalmente. Solución: siempre comprueba stream.Err() después del bucle, no solo dentro de él.
• Asumir que Content[0] es siempre texto - una respuesta con tool_use pone un ToolUseBlock en Content, no un bloque de texto, y indexar ciegamente provoca un pánico. Solución: comprueba el tipo de block.AsAny(), o comprueba StopReason antes de leer Content[0].Text.
• Olvidar que MaxTokens es obligatorio - omitirlo produce un error de validación en tiempo de solicitud en lugar de un valor predeterminado sensato. Solución: establece siempre un MaxTokens explícito del tamaño de tu respuesta esperada.
• No pasar un contexto cancelable bajo carga - usar context.Background() en todas partes significa que una solicitud lenta o colgada no puede ser cancelada por un tiempo de espera anterior. Solución: pasa un context.Context con un plazo o cancelación, con ámbito de solicitud, a través de cada llamada.
• Tratar tool_use como la respuesta final - recibir un bloque tool_use significa que Claude está esperando un tool_result, no que la tarea esté terminada. Solución: ejecuta la herramienta, luego envía el resultado de vuelta en una llamada Messages.New de seguimiento antes de considerar la conversación completa.

Alternativas

Preguntas frecuentes

Relacionados

• Conceptos básicos de otros SDK oficiales - una primera llamada en cada uno de los cinco idiomas, incluido un ejemplo más simple de Go
• Uso idiomático de herramientas en Go, Java, C#, PHP y Ruby - compara este patrón de tool_use con los otros cuatro SDK
• Más allá de Python y TypeScript: Los otros SDK oficiales de Claude - la descripción conceptual en la que se basa este artículo
• Construcción de un bucle de uso de herramientas de múltiples turnos - el bucle completo de solicitud/resultado de herramienta/seguimiento, en términos generales
• Cómo los eventos enviados por el servidor potencian las respuestas de streaming de Claude - el protocolo de streaming que consume este ejemplo de Go

Versiones de pila: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y los SDK oficiales actuales para Go, Java, C#, PHP y Ruby. Los nombres de los modelos, las versiones de los SDK y los precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.