Claude Agent SDK: el SDK oficial de Anthropic para agentes IA

# TypeScript / JavaScript
npm install @anthropic-ai/claude-code

# Python
pip install anthropic

# Con uv (recomendado para proyectos Python nuevos)
uv add anthropic

import Anthropic from "@anthropic-ai/claude-code";

const client = new Anthropic();

// Definicion de herramienta: nombre, descripcion y schema de parametros
const getWeatherTool = {
  name: "get_weather",
  description:
    "Obtiene el clima actual para una ciudad. " +
    "Usa esta herramienta cuando el usuario pregunte sobre el tiempo.",
  input_schema: {
    type: "object" as const,
    properties: {
      city: {
        type: "string",
        description: "Nombre de la ciudad",
      },
      unit: {
        type: "string",
        enum: ["celsius", "fahrenheit"],
        description: "Unidad de temperatura",
      },
    },
    required: ["city"],
  },
};

// Implementacion de la herramienta
function getWeather(city: string, unit = "celsius"): string {
  // En produccion aqui iria una llamada a una API meteorologica real
  return JSON.stringify({
    city,
    temperature: unit === "celsius" ? 22 : 72,
    condition: "Parcialmente nublado",
    humidity: "65%",
  });
}

// Instancia del agente
const agent = new Anthropic.Agent({
  model: "claude-sonnet-4-6",
  instructions:
    "Eres un asistente meteorologico preciso. " +
    "Usa siempre la herramienta get_weather para obtener datos actuales. " +
    "Responde en espanol y usa grados Celsius.",
  tools: [getWeatherTool],
});

// Bucle de ejecucion con gestion de herramientas
async function runAgent(userMessage: string): Promise {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: userMessage },
  ];

  while (true) {
    const response = await agent.run(messages);

    if (response.stop_reason === "end_turn") {
      // El agente ha terminado: imprimir la respuesta final
      const text = response.content.find((b) => b.type === "text");
      if (text && text.type === "text") {
        console.log("Agente:", text.text);
      }
      break;
    }

    if (response.stop_reason === "tool_use") {
      // El agente quiere invocar una herramienta
      messages.push({ role: "assistant", content: response.content });

      const toolResults: Anthropic.ToolResultBlockParam[] = [];

      for (const block of response.content) {
        if (block.type === "tool_use") {
          const input = block.input as { city: string; unit?: string };
          const result = getWeather(input.city, input.unit);
          toolResults.push({
            type: "tool_result",
            tool_use_id: block.id,
            content: result,
          });
        }
      }

      messages.push({ role: "user", content: toolResults });
    }
  }
}

runAgent("Que tiempo hace hoy en Madrid?");

import anthropic
import json

client = anthropic.Anthropic()

# Herramienta de busqueda simulada
def search_knowledge_base(query: str, max_results: int = 3) -> str:
    """
    Busca en la base de conocimiento interna.
    Usa esta herramienta para responder preguntas sobre productos y politicas.

    Args:
        query: Termino o pregunta a buscar.
        max_results: Numero maximo de resultados a devolver.

    Returns:
        Resultados relevantes en formato JSON.
    """
    # En produccion: llamada real a una BD vectorial o buscador
    results = [
        {"id": 1, "title": "Politica de devolucion", "content": "30 dias desde la compra..."},
        {"id": 2, "title": "Soporte tecnico", "content": "Disponible 24/7 via chat..."},
    ]
    return json.dumps(results[:max_results], ensure_ascii=False)


# Definicion del agente
MODEL = "claude-sonnet-4-6"
SYSTEM = (
    "Eres un agente de soporte al cliente experto. "
    "Usa la herramienta search_knowledge_base para encontrar informacion precisa "
    "antes de responder. Nunca inventes datos. Responde siempre en espanol."
)

TOOLS = [
    {
        "name": "search_knowledge_base",
        "description": (
            "Busca en la base de conocimiento interna sobre productos, politicas y soporte. "
            "Usa esta herramienta siempre que el usuario pregunte algo especifico."
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "Consulta a buscar"},
                "max_results": {
                    "type": "integer",
                    "description": "Resultados maximos",
                    "default": 3,
                },
            },
            "required": ["query"],
        },
    }
]

def process_tool_call(tool_name: str, tool_input: dict) -> str:
    """Enruta la llamada a la funcion correcta."""
    if tool_name == "search_knowledge_base":
        return search_knowledge_base(**tool_input)
    return json.dumps({"error": f"Herramienta desconocida: {tool_name}"})


def chat(conversation_history: list, user_message: str) -> tuple[str, list]:
    """
    Ejecuta un turno de conversacion y devuelve la respuesta y el historial actualizado.
    """
    conversation_history.append({"role": "user", "content": user_message})

    while True:
        response = client.messages.create(
            model=MODEL,
            max_tokens=4096,
            system=SYSTEM,
            tools=TOOLS,
            messages=conversation_history,
        )

        if response.stop_reason == "end_turn":
            # Respuesta final del agente
            assistant_message = response.content[0].text
            conversation_history.append(
                {"role": "assistant", "content": response.content}
            )
            return assistant_message, conversation_history

        if response.stop_reason == "tool_use":
            # Procesar llamadas a herramientas
            conversation_history.append(
                {"role": "assistant", "content": response.content}
            )
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    result = process_tool_call(block.name, block.input)
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result,
                    })
            conversation_history.append({"role": "user", "content": tool_results})


# Uso
history = []
reply, history = chat(history, "Cual es vuestra politica de devoluciones?")
print(f"Agente: {reply}")

reply, history = chat(history, "Y si el producto esta defectuoso?")
print(f"Agente: {reply}")