Ir al contenido principal
Español— Elegir un idioma
Menú

Competencias: encapsulación de capacidades

Lección 17 de 20 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Competencias: encapsulación de capacidades
  2. El concepto de competencia
  3. Estructuración de una biblioteca de competencias
  4. Composición de competencias
  5. Competencias con estado
  6. Registro de competencias
  7. Puntos clave

Lección actualizada el 2 de noviembre de 2026 según la documentación de OpenAI: la herramienta Code Interpreter requiere ahora un parámetro container (añadido a todos los ejemplos), las partes de entrada de texto son de tipo input_text, y la búsqueda web utiliza la herramienta web_search (web_search_preview es ahora una herramienta heredada sin filtros de dominio). Los archivos generados se recuperan mediante las funciones fichiers_generes y telecharger de la Lección 10. Fuentes: Code Interpreter · Búsqueda web.

Competencias: encapsulación de capacidades

Una competencia resuelve un problema con el que todos se topan en la segunda semana: el mismo mensaje del sistema copiado en cuatro archivos, que divergen en cuanto mejoras solo uno. La idea consiste en tratar una capacidad como una unidad única —sus instrucciones, sus herramientas, sus datos de referencia— y llamarla por su nombre en lugar de reescribirla.

La ventaja no es solo evitar la repetición. Una capacidad nombrada se convierte en un objeto que puedes versionar, probar y entregar a otra persona. Cuando un abogado te indica que una cláusula estándar ha cambiado, modificas una única competencia y todas las llamadas se benefician, en lugar de tener que rastrear dónde se duplicó el mensaje.

El concepto de competencia

Una competencia encapsula todo lo que un modelo necesita para llevar a cabo una tarea específica. Los tres elementos siguientes no son intercambiables: las instrucciones definen el rol y el formato, las herramientas determinan qué puede consultar el modelo, y el contexto ancla las respuestas en tus propias referencias en lugar de en el conocimiento general del modelo.

  • Instrucciones: el mensaje del sistema especializado
  • Herramientas: las funciones y herramientas integradas necesarias
  • Contexto: datos de referencia y ejemplos
from openai import OpenAI

client = OpenAI()

# Definir una competencia de análisis financiero
skill_analyse_financiere = {
    "instructions": (
        "You are a financial analyst specializing in French SMEs. "
        "You analyze accounting documents and produce structured reports "
        "with key indicators, trends, and recommendations. "
        "Use French accounting standards (PCG). "
        "Format amounts in euros with thousands separators."
    ),
    "tools": [
        {"type": "file_search", "vector_store_ids": ["vs_normes_comptables"]},
        {"type": "code_interpreter", "container": {"type": "auto"}}
    ]
}

# Usar la competencia
response = client.responses.create(
    model="gpt-5.6-terra",
    instructions=skill_analyse_financiere["instructions"],
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "Analyze this balance sheet and produce a report"},
            {"type": "input_file", "file_id": fichier_bilan.id}
        ]
    }],
    tools=skill_analyse_financiere["tools"]
)

Estructuración de una biblioteca de competencias

Pasar de un diccionario a una clase no es solo cosmético: te permite adjuntar ejemplos a una competencia e inyectarlos de forma sistemática. Dos o tres pares de entrada/salida bien elegidos hacen más por la coherencia del formato que un párrafo adicional de instrucciones, porque muestran en lugar de describir. La implementación siguiente los concatena a las instrucciones en cada llamada.

class Skill:
    def __init__(self, nom: str, instructions: str, tools: list, exemples: list = None):
        self.nom = nom
        self.instructions = instructions
        self.tools = tools
        self.exemples = exemples or []

    def executer(self, client: OpenAI, requete: str, fichiers: list = None) -> str:
        content = [{"type": "input_text", "text": requete}]
        if fichiers:
            for fid in fichiers:
                content.append({"type": "input_file", "file_id": fid})

        # Añadir ejemplos al contexto
        instructions = self.instructions
        if self.exemples:
            instructions += "\n\nReference examples:\n"
            for ex in self.exemples:
                instructions += f"- Input: {ex['input']}\n  Output: {ex['output']}\n"

        response = client.responses.create(
            model="gpt-5.6-terra",
            instructions=instructions,
            input=[{"role": "user", "content": content}],
            tools=self.tools
        )
        return response.output_text


# Definir competencias
skill_redaction_contrat = Skill(
    nom="redaction-contrat",
    instructions=(
        "You are a lawyer specializing in contract law. "
        "You draft clear, precise clauses compliant with French law. "
        "Each clause must be numbered and structured."
    ),
    tools=[
        {"type": "file_search", "vector_store_ids": ["vs_modeles_contrats"]},
        {"type": "web_search"}
    ],
    exemples=[
        {
            "input": "Confidentiality clause for a contractor",
            "output": "Article X - Confidentiality\nX.1 The Contractor undertakes..."
        }
    ]
)

skill_support_technique = Skill(
    nom="support-technique",
    instructions=(
        "You are a level 2 technical support agent. "
        "You diagnose problems by asking targeted questions. "
        "Search the knowledge base first before proposing solutions. "
        "Document every resolution."
    ),
    tools=[
        {"type": "file_search", "vector_store_ids": ["vs_base_connaissances"]},
        {
            "type": "function",
            "name": "creer_ticket_escalade",
            "description": "Escalate an issue to level 3",
            "parameters": {
                "type": "object",
                "properties": {
                    "titre": {"type": "string"},
                    "description": {"type": "string"},
                    "priorite": {"type": "string", "enum": ["basse", "moyenne", "haute", "critique"]}
                },
                "required": ["titre", "description", "priorite"],
                "additionalProperties": False
            },
            "strict": True
        }
    ]
)

Composición de competencias

La composición encadena competencias pasando el resultado de una como contexto a la siguiente. Es potente, y ahí es precisamente donde empiezan los problemas, por una razón concreta: en cada paso, el contexto transmitido es la salida del paso anterior, no los datos originales. Cualquier información que la primera competencia considerase secundaria desaparece para todas las siguientes.

Dos consecuencias prácticas. Ordena los pasos de lo más general a lo más específico, de modo que el filtrado ocurra lo más tarde posible. Y cuando un paso posterior necesite datos en bruto, vuelve a pasar los archivos en lugar de confiar en el resumen; eso es exactamente lo que hace el parámetro fichiers en el ejemplo, que se pasa solo al primer paso pero debería pasarse a todos los que dependan de él.

class SkillComposee:
    def __init__(self, nom: str, etapes: list[dict]):
        self.nom = nom
        self.etapes = etapes
        self.client = OpenAI()

    def executer(self, requete_initiale: str, fichiers: list = None) -> dict:
        contexte = requete_initiale
        resultats = {}

        for etape in self.etapes:
            skill = etape["skill"]
            instruction_etape = etape.get("instruction", "")
            prompt = f"{instruction_etape}\n\nPrevious context: {contexte}"

            resultat = skill.executer(self.client, prompt, fichiers)
            resultats[etape["nom"]] = resultat
            contexte = resultat
            fichiers = None  # Files used only at the first step

        return resultats


# Flujo de trabajo: análisis de contrato seguido de redacción de resumen
workflow_audit_contrat = SkillComposee(
    nom="audit-contrat",
    etapes=[
        {
            "nom": "analyse",
            "skill": skill_analyse_financiere,
            "instruction": "Analyze the financial aspects of this contract"
        },
        {
            "nom": "juridique",
            "skill": skill_redaction_contrat,
            "instruction": "Identify legal risks and propose improvements"
        }
    ]
)

Competencias con estado

Una competencia que recuerda sus llamadas anteriores permite conversaciones largas —un diagnóstico técnico, una negociación, seguimiento de casos—. También introduce el único coste que crece sin que te des cuenta: en cada turno, se reenvía y se vuelve a facturar todo el historial. Planifica desde el inicio una política de truncamiento o resumen periódico, o la vigésima pregunta costará diez veces más que la primera sin que la calidad haya mejorado diez veces.

class SkillAvecEtat:
    def __init__(self, skill: Skill):
        self.skill = skill
        self.client = OpenAI()
        self.historique = []
        self.contexte_accumule = ""

    def appeler(self, requete: str, fichiers: list = None) -> str:
        # Construir el mensaje con el historial
        instructions = self.skill.instructions
        if self.contexte_accumule:
            instructions += f"\n\nContext from previous interactions:\n{self.contexte_accumule}"

        content = [{"type": "input_text", "text": requete}]
        if fichiers:
            for fid in fichiers:
                content.append({"type": "input_file", "file_id": fid})

        response = self.client.responses.create(
            model="gpt-5.6-terra",
            instructions=instructions,
            input=[{"role": "user", "content": content}],
            tools=self.skill.tools
        )

        resultat = response.output_text
        self.historique.append({"requête": requete, "reponse": resultat})
        self.contexte_accumule += f"\n- {requete} -> {resultat[:200]}..."

        return resultat

# Uso: soporte técnico con seguimiento de conversación
session = SkillAvecEtat(skill_support_technique)
r1 = session.appeler("My application crashes at startup")
r2 = session.appeler("I have version 3.2.1 on Ubuntu 24.04")
r3 = session.appeler("The log shows a database connection error")

Registro de competencias

Centraliza la gestión de tus competencias:

class RegistreSkills:
    def __init__(self):
        self.skills = {}

    def enregistrer(self, skill: Skill):
        self.skills[skill.nom] = skill

    def obtenir(self, nom: str) -> Skill:
        if nom not in self.skills:
            raise KeyError(f"Skill '{nom}' not found. "
                          f"Available: {list(self.skills.keys())}")
        return self.skills[nom]

    def lister(self) -> list[str]:
        return list(self.skills.keys())

# Registro global
registre = RegistreSkills()
registre.enregistrer(skill_analyse_financiere_obj)
registre.enregistrer(skill_redaction_contrat)
registre.enregistrer(skill_support_technique)

# Uso
skill = registre.obtenir("support-technique")
resultat = skill.executer(client, "My printer isn't working")

Puntos clave

  • Una competencia encapsula instrucciones, herramientas y contexto en un paquete reutilizable
  • Compón competencias para flujos de trabajo de varios pasos
  • Usa estado para competencias conversacionales
  • Centraliza tus competencias en un registro para simplificar su descubrimiento
  • Los ejemplos en las instrucciones mejoran la precisión del modelo