Camins d’Habilitats Onboarding

Propòsit

Aquesta guia és el camí d’integració únic per a ambdós modes d’ús de Decision Gate:

1. DG guarda l’execució de competències externes.
2. DG es coneix com una habilitat d’avaluació determinista.

També defineix com compondre ambdós modes de manera segura (bucles recursius) sense permetre la deriva de polítiques autoritzades per LLM.

Quin camí utilitzar

Intent	Path	Enforcement Strength
Mutar l’estat extern (deploy, delete, pay, publish)	DG protege l’execució de habilitats	Límite dur (fallar-tancat)
Produir anàlisi/informes/suport a la decisió	DG com a habilitat d’avaluació	Càlcul només a menys que estigui embolcallat per un límit
Cicles d’agents de múltiples passos que autoritzen i després executen	Composició recursiva (guàrdia exterior + avaluació interior)	Límite dur a l’anell exterior

Camí A: Execució de les habilitats dels guàrdies DG (Predeterminat de producció)

Utilitzeu això quan les accions tinguin efectes secundaris.

Contracte Operatiu

1. La propietat de la porta és humana/propietat de polítiques.
2. Les especificacions de la porta són artefactes versionats, no inventions de LLM en temps d’execució.
3. Cada truc de habilitat mutadora ha de passar l’avaluació DG en viu abans de l’execució.
4. Els resultats no vàlids (hold, fail, unknown) bloquegen l’execució.

Llista de verificació de configuració

1. Define un mapa de portes per acció.
2. Autor i registrar les especificacions de l’escenari per a cada classe d’acció.
3. Implementar un wrapper de runtime prim: evaluate -> allow/deny -> execute.
4. Exporta i verifica els runpacks per a l’auditoria.

Exemple de mapa d’accions:

{
  "deploy_to_prod": {
    "scenario_id": "release-boundary-v1",
    "required_min_lane": "verified",
    "allowed_outcomes": ["advance", "complete"]
  },
  "publish_external_report": {
    "scenario_id": "publication-boundary-v1",
    "required_min_lane": "verified",
    "allowed_outcomes": ["complete"]
  }
}

Exemple de lògica de wrapper:

def guarded_skill_call(action_name, action_args):
    policy = action_gate_map[action_name]
    run_id = start_run(policy["scenario_id"])
    result = scenario_next(policy["scenario_id"], run_id, feedback="trace")
    outcome = extract_outcome_kind(result)
    if outcome not in policy["allowed_outcomes"]:
        return {"allowed": False, "reason": "gate_not_satisfied", "result": result}
    skill_result = call_external_skill(action_name, action_args)
    runpack = runpack_export(policy["scenario_id"], run_id)
    verify = runpack_verify(runpack["dir"], runpack["manifest_path"])
    return {"allowed": True, "skill_result": skill_result, "runpack_verify": verify}

Referències d’implementació:

• scenario_define, scenario_start, scenario_next: integration_patterns.md
• runpack audit path: integration_patterns.md
• exemple de flux en viu de principi a fi: openai_agents_live_loop.py

Camí B: Habilitat d’Avaluació DG

Utilitzeu això per a l’anàlisi estructurada quan no s’executa cap acció d’efecte secundari directe.

Contracte Operatiu

1. DG s’invoca com a un avaluador de reclamacions determinista.
2. Les sortides impulsen l’explicació/informe, no la mutació directa.
3. Si es sol·licita una mutació més tard, canvia primer a la frontera del Camí A.

Flux d’Eines Típic

1. Descobreix capacitats: providers_list, provider_contract_get, provider_check_schema_get.
2. Construir artefactes: claim_inventory, capability_matrix, claim_condition_map.
3. Avaluar: precheck per a la iteració, després scenario_next en viu quan la política requereix prova en viu.
4. Verifiqueu la integritat quan s’exigeixi una auditoria: runpack_export, runpack_verify.

Contracte canònic: llm_native_playbook.md

Camí C: Composició Recursiva (Cicle d’Autoria + Límits d’Execució)

Aquesta és la preocupació comuna del “flux de treball DG dins de DG”.

Utilitza un model d’anell:

1. Anell interior: DG-as-skill per a l’assistència en la descomposició/verificació de reclamacions.
2. Anell exterior: guarda DG per a l’acció conseqüent.

Regles estrictes:

1. El cercle interior pot proposar mapes; no pot relaxar la política del cercle exterior.
2. Les definicions de la porta de l’anell exterior romanen autoritzades pel sistema i versionades.
3. Bloquejos de l’anell exterior sobre qualsevol reclam requerit no resolt independentment del text de confiança de l’anell interior.
4. La verificació de Runpack a l’anell exterior és la font d’auditoria de veritat.

Patró anti a evitar:

"The agent self-evaluated with DG and therefore can deploy."

Patró correcte:

"The agent used DG for analysis, then the system-enforced deployment gate passed live, then deploy executed."

Ruta d’Integració Ràpida (Repositori)

Utilitzeu aquesta seqüència quan incorporeu humans o agents LLM a ambdós camins.

1. Executa el ràpid inici de comanda provat (ambdues rutes + cas de denegació forçada):

scripts/bootstrap/skill_pathways_quickstart.sh configs/presets/quickstart-dev.toml

2. Llegeix llm_native_playbook.md i aquesta guia.
3. Instal·lar habilitats:

scripts/skills/install_local.sh

4. Executar el procés d’integració de principi a fi:

python3 examples/frameworks/openai_agents_live_loop.py \
  --fixture-dir examples/agentic/onboarding/basic

5. Executar la matriu de correcció determinista:

python3 scripts/skills/eval_runner.py \
  --mode deterministic \
  --trials 1 \
  --cases all \
  --out-dir .tmp/skills/eval-deterministic-local

6. Executar el verificador de correcció d’integració:

python3 scripts/onboarding/provider_onboarding_check.py \
  --cases all \
  --out-dir .tmp/onboarding/local

Definició de Fet (Mínim Sense Errors)

Abans de declarar l’adopció completa:

1. Les habilitats de mutació estan envoltades per la lògica de límit del Camí A.
2. Les especificacions de la porta són versionades i propietat de la política (no text de prompt ad hoc).
3. Les instruccions orientades a LLM inclouen regles de parada estrictes explícites.
4. Els informes d’evaluació de competències deterministes passen per als casos requerits.
5. El informe de correcció d’integració marca tots els casos com a complets.
6. Passos de verificació de runpack en fluxos de treball de límit en viu.

Referències Creuades

• llm_native_playbook.md
• patrons_d’integració.md
• openai_agents_onboarding_playbook.md
• README.md