Competências: Encapsular Capacidades
Nesta página
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 tipoinput_texte a pesquisa na web utiliza a ferramentaweb_search(web_search_previewé agora uma ferramenta legada sem filtros de domínio). Os ficheiros gerados são recuperados utilizando as funçõesfichiers_generesetelechargerda 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