Uso Idiomático de Herramientas en Go, Java, C#, PHP y Ruby

El uso de herramientas (tool_use) es el mismo protocolo en todas partes donde se ejecuta Claude, pero definir un esquema de herramienta y leer el resultado se ve diferente en cada lenguaje. Esta página compara esa sintaxis en los cinco SDKs oficiales más allá de Python y TypeScript.

Cómo Usar Esta Lista

• Lee la entrada para tu lenguaje primero, luego hojea las otras para reconocer el patrón cuando leas ejemplos entre lenguajes.
• Cada ejemplo define la misma herramienta (una función get_weather que toma una cadena city) para que la comparación sea directa.
• El protocolo de comunicación (lo que Claude realmente envía y espera recibir) es idéntico en los cinco; solo cambia la sintaxis del lenguaje anfitrión.
• Empareja esto con el bucle general de tool_use (solicitud, bloque tool_use, ejecutar la herramienta, enviar tool_result) si no has visto ese flujo antes.

Go: Esquemas Basados en Structs

Go describe el esquema de entrada de una herramienta como un struct tipado más un ToolInputSchemaParam explícito, y lee los resultados cambiando el tipo de los bloques de contenido.

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"},
    },
}
 
for _, block := range message.Content {
    if toolUse, ok := block.AsAny().(anthropic.ToolUseBlock); ok {
        var input WeatherInput
        json.Unmarshal(toolUse.Input, &input)
    }
}

• El esquema se construye a partir de las etiquetas json de un struct de Go más un mapa Properties explícito; Go no tiene reflexión de JSON Schema incorporada, por lo que escribes ambos a mano.
• Leer un resultado significa cambiar el tipo de block.AsAny() para encontrar un ToolUseBlock, luego hacer json.Unmarshal de los bytes crudos de Input en tu propio struct tipado.
• Este es el más verboso de los cinco, a cambio de la verificación de campos en tiempo de compilación en el destino de unmarshal.

Java: Esquemas con Patrón Builder

Java expresa el mismo esquema a través de su patrón builder y lee los resultados inspeccionando objetos de bloque de contenido tipados.

Tool weatherTool = Tool.builder()
    .name("get_weather")
    .description("Obtener el clima actual de una ciudad.")
    .inputSchema(Tool.InputSchema.builder()
        .properties(JsonValue.from(Map.of(
            "city", Map.of("type", "string")
        )))
        .putAdditionalProperty("required", JsonValue.from(List.of("city")))
        .build())
    .build();
 
for (ContentBlock block : message.content()) {
    if (block.isToolUse()) {
        ToolUseBlock toolUse = block.asToolUse();
        String city = toolUse.input().asObject().get("city").asString().get();
    }
}

• Tool.builder() refleja la misma convención de builder fluida que Java usa en todas partes, incluso para la solicitud de mensaje en sí.
• Las propiedades del esquema de entrada se construyen como un Map envuelto en JsonValue, ya que Java no tiene sintaxis nativa de literales JSON.
• Leer un resultado significa verificar block.isToolUse() antes de llamar a block.asToolUse(), luego navegar por el JSON de entrada como un árbol genérico en lugar de hacer unmarshal automáticamente a un POJO.

C#: Objetos de Solicitud Tipados

C# define el esquema como un objeto tipado y lee los resultados a través de la coincidencia de patrones en los tipos de bloque de contenido.

var weatherTool = new Tool
{
    Name = "get_weather",
    Description = "Get the current weather for a city.",
    InputSchema = new
    {
        type = "object",
        properties = new { city = new { type = "string" } },
        required = new[] { "city" }
    }
};
 
foreach (var block in response.Content)
{
    if (block is ToolUseContent toolUse)
    {
        var city = toolUse.Input["city"].ToString();
    }
}

• InputSchema a menudo se construye como un objeto anónimo serializado a JSON, ya que C# no tiene un tipo JSON Schema de primera clase en el SDK.
• El manejo de resultados utiliza el operador is de coincidencia de patrones de C# para verificar el tipo en tiempo de ejecución del bloque, el equivalente en C# del switch de tipos de Go o la verificación isToolUse() de Java.
• toolUse.Input suele ser una estructura similar a un diccionario en la que se indexa por clave, más parecido al enfoque de PHP y Ruby que al patrón estricto de unmarshal a struct de Go.

PHP: Arrays Asociativos

PHP no tiene tipado en tiempo de compilación para esto, por lo que tanto el esquema como el resultado son simples arrays asociativos.

$weatherTool = [
    'name' => 'get_weather',
    'description' => 'Get the current weather for a city.',
    'input_schema' => [
        'type' => 'object',
        'properties' => [
            'city' => ['type' => 'string'],
        ],
        'required' => ['city'],
    ],
];
 
foreach ($response->content as $block) {
    if ($block->type === 'tool_use') {
        $city = $block->input['city'];
    }
}

• El esquema de la herramienta se escribe como un array asociativo anidado que refleja directamente la forma del JSON Schema, clave por clave.
• El manejo de resultados verifica $block->type === 'tool_use' y luego indexa $block->input como un array normal de PHP, ya que PHP no hace unmarshal a clases tipadas por defecto.
• Este es el menos ceremonioso de los cinco: sin builders, sin structs, solo arrays que coinciden casi textualmente con el formato de comunicación.

Ruby: Hashes

El enfoque de Ruby es similar al de PHP, utilizando hashes con claves simbólicas en lugar de arrays asociativos.

weather_tool = {
  name: "get_weather",
  description: "Get the current weather for a city.",
  input_schema: {
    type: "object",
    properties: {
      city: { type: "string" }
    },
    required: ["city"]
  }
}
 
response.content.each do |block|
  if block.type == "tool_use"
    city = block.input["city"]
  end
end

• El hash del esquema utiliza claves simbólicas (city:) en lugar de claves de cadena, lo cual es idiomático en Ruby pero aún se serializa al mismo JSON Schema que espera la API de Mensajes.
• El manejo de resultados verifica block.type == "tool_use" y lee block.input como un hash, la misma forma que PHP produce a partir de su array asociativo.
• Ruby y PHP son el par más cercano aquí: ambos omiten por completo el tipado estático y dejan que la forma del hash/array haga el trabajo.

Comparación de los Cinco de un Vistazo

Manejo del Resultado: La Forma Compartida

Independientemente del lenguaje, todos los SDKs esperan el mismo siguiente paso una vez que has leído un bloque tool_use: ejecutar la herramienta y luego enviar un mensaje tool_result a Claude haciendo referencia al ID del tool_use.

resultMessage := anthropic.NewUserMessage(
    anthropic.NewToolResultBlock(toolUse.ID, weatherJSON, false),
)

• El bloque tool_result siempre lleva el ID del bloque tool_use original, para que Claude pueda emparejar el resultado con la llamada que hizo.
• Este requisito de coincidencia de ID es idéntico en los cinco SDKs; solo la sintaxis para construir el bloque de resultado difiere.
• Omitir este paso, o enviar un tool_result con un ID que no coincide, produce una solicitud que la API de Mensajes rechaza de la misma manera en todos los lenguajes.

Preguntas Frecuentes

Relacionado

• Llamando a Claude desde Go con el SDK Oficial - un ejemplo completo y ejecutable de tool_use en Go con la solicitud de seguimiento incluida
• Fundamentos de Otros SDKs Oficiales - primeras llamadas en cada uno de los cinco lenguajes antes de agregar herramientas
• Más allá de Python y TypeScript: Los Otros SDKs Oficiales de Claude - por qué estos SDKs divergen idiomáticamente a pesar de compartir un protocolo
• Construyendo un Bucle de Uso de Herramientas Multi-Turno - el flujo agnóstico al lenguaje de solicitud/tool_result/seguimiento
• Definición de Esquemas de Herramientas con Nombre, Descripción y Esquema de Entrada - la forma JSON Schema que la sintaxis de cada lenguaje produce finalmente

Versiones de Stack: 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 SDKs oficiales actuales para Go, Java, C#, PHP y Ruby. Los nombres de modelos, versiones de SDK y precios cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.