Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Competências: Encapsular Capacidades

Aula 17 de 20 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Competências: Encapsular Capacidades
  2. O Conceito de Competência
  3. Estruturar uma Biblioteca de Competências
  4. Compor Competências
  5. Competências com Estado
  6. Registo de Competências
  7. Pontos-chave

Lição atualizada em 2 de novembro de 2026 com base na documentação da OpenAI: a ferramenta Code Interpreter requer agora um parâmetro container (adicionado a todos os exemplos), as partes de entrada de texto são do tipo input_text e a pesquisa na web utiliza a ferramenta web_search (web_search_preview é agora uma ferramenta legada sem filtros de domínio). Os ficheiros gerados são recuperados utilizando as funções fichiers_generes e telecharger da Lição 10. Fontes: Code Interpreter · Web search.

Competências: Encapsular Capacidades

Uma Competência (Skill) resolve um problema que todos enfrentam na segunda semana: o mesmo prompt de sistema copiado em quatro ficheiros, divergindo assim que melhora apenas um deles. A ideia é tratar uma capacidade como uma unidade única — as suas instruções, as suas ferramentas, os seus dados de referência — e invocá-la pelo nome, em vez de a reescrever.

A vantagem não é apenas evitar a repetição. Uma capacidade nomeada torna-se num objeto que pode versionar, testar e entregar a outra pessoa. Quando um advogado lhe diz que uma cláusula padrão mudou, modifica uma competência e todas as chamadas beneficiam — em vez de procurar onde o prompt foi duplicado.

O Conceito de Competência

Uma Competência encapsula tudo o que um modelo necessita para realizar uma tarefa específica. Os três elementos abaixo não são intercambiáveis: as instruções definem o papel e o formato, as ferramentas determinam o que o modelo pode obter e o contexto ancora as respostas nas suas próprias referências, em vez do conhecimento geral do modelo.

  • Instruções: O prompt de sistema especializado
  • Ferramentas: As funções e ferramentas integradas necessárias
  • Contexto: Dados de referência e exemplos
from openai import OpenAI

client = OpenAI()

# Definir uma competência de análise financeira
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"}}
    ]
}

# Utilizar a competência
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"]
)

Estruturar uma Biblioteca de Competências

Passar de um dicionário para uma classe não é apenas cosmético: permite-lhe anexar exemplos a uma competência e injetá-los sistematicamente. Dois ou três pares de entrada/saída bem escolhidos fazem mais pela consistência do formato do que um parágrafo extra de instruções, porque mostram em vez de descrever. A implementação abaixo concatena-os às instruções em cada chamada.

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})

        # Adicionar exemplos ao 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 competências
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
        }
    ]
)

Compor Competências

A composição encadeia competências passando o resultado de uma como contexto para a seguinte. É poderoso, e é exatamente aí que começam os problemas, por uma razão específica: em cada passo, o contexto transmitido é a saída do passo anterior, não os dados originais. Qualquer informação que a primeira competência considerou secundária desaparece para todas as subsequentes.

Duas consequências práticas. Ordene os passos do mais geral para o mais específico, para que a filtragem ocorra o mais tarde possível. E quando um passo a jusante necessitar de dados brutos, passe novamente os ficheiros em vez de confiar no resumo — é precisamente isso que o parâmetro fichiers no exemplo faz, que é passado apenas ao primeiro passo, mas deve ser passado a todos os que dele dependem.

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


# Fluxo de trabalho: análise de contrato seguida de redação de resumo
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"
        }
    ]
)

Competências com Estado

Uma competência que recorda as suas chamadas anteriores permite conversas longas — um diagnóstico técnico, uma negociação, acompanhamento de casos. Também introduz o único custo que cresce despercebidamente: a cada volta, todo o histórico é reenviado e refaturado. Planeie uma política de truncagem ou resumo periódico desde o início, ou a vigésima pergunta custará dez vezes mais que a primeira, por uma qualidade que não melhorou dez vezes.

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 prompt com histórico
        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

# Utilização: suporte técnico com acompanhamento de conversação
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")

Registo de Competências

Centralize a gestão das suas competências:

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())

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

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

Pontos-chave

  • Uma Competência encapsula instruções, ferramentas e contexto num pacote reutilizável
  • Componha competências para fluxos de trabalho em várias etapas
  • Utilize estado para competências conversacionais
  • Centralize as suas competências num registo para simplificar a descoberta
  • Exemplos nas instruções melhoram a precisão do modelo