Orqestria Letöltés
← Freya adatlapja
AgentFreya

Skill · 1.0.0 verzió

Eszközhívási szerződések

Egyértelmű AI-eszközt tervez korlátozott bemenettel, ellenőrzött végrehajtással és hasznos kontextust megőrző kimenettel.

tool-calling-contracts

Nézd meg, miben segít

Mikor hasznos?

Akkor használd, ha modell rossz műveletet választ vagy túlméretes eredményt kap.

Miben segít neked?

  • Világos területi műveletet és pontos sémafeltételt használ.
  • Elválasztja az argumentum-, jogosultság- és üzletiszabály-ellenőrzést.
  • Strukturált hibát és korlátos kimenetet ad értelmes helyreállításhoz.

Például ezt kérheted

Tervezz projektkeresőt korlátozott találattal és kifejezett hibával hozzáférhetetlen projektre. Kérj túl sok találatot és idegen projektazonosítót. Korlátos, típusos válasz érkezzen, az elutasítás ne áruljon el elérhetetlen projektrészletet.

Részletes dokumentáció

Itt a skill eredeti útmutatóját, példáit és ellenőrzési szempontjait olvashatod az eredeti nyelven.

Részletek…Összecsukás

Tool Calling & Execution Contracts

Tools are the API boundary between a probabilistic model and deterministic application state. Design every tool so its contract is unmistakable to the model, strictly validated at runtime, bounded in output size, and safe under retries.

Designing High-Signal Tool Schemas

  1. Action-oriented, unambiguous names: Use snake_case verbs scoped by domain (orders_get_by_id, repo_search_code, calendar_propose_slot). Avoid overloaded swiss-army tools with modal action: "create" | "update" | "delete" | "search" parameters when separate tools have distinct schemas and permission levels.
  2. Tight JSON Schema constraints:
    • Set "additionalProperties": false on object schemas so hallucinated fields fail fast.
    • Prefer enum, bounded numeric ranges (minimum, maximum), and pattern-constrained strings over free-form string.
    • Write parameter description fields that state units, format, and preconditions (e.g., "ISO-8601 UTC timestamp (YYYY-MM-DDTHH:mm:ssZ). Must be >= start_time.").
  3. Behavioral annotations: Attach explicit metadata to every tool registration:
    • readOnlyHint: true if the tool never mutates state.
    • destructiveHint: true if the tool deletes or overwrites data irreversibly.
    • idempotentHint: true if repeated calls with identical arguments have no additional effect.
    • timeoutMs and maxOutputBytes: Explicit execution bounds enforced by the dispatcher.

Three-Layer Validation & Error Recovery

Distinguish protocol errors from model-correctable tool failures:

Failure Class Example How the Dispatcher Must Respond
Schema / Argument Validation Missing required field, invalid enum value, malformed date Do not throw an unhandled exception. Return a tool result with isError: true listing the exact JSON path and expected constraint so the model can self-correct on the next turn.
Domain / Precondition Error Order #4821 not found, File modified since last read, Insufficient permissions Return isError: true with a concise, structured recovery hint (e.g., "File changed on disk; call read_file before editing").
Transient Infrastructure Failure 429, 503, connection reset on an idempotent backend Retry inside the tool adapter with exponential backoff + jitter before surfacing a failure to the model.
Fatal Runtime / Bug Null pointer in tool implementation, revoked service credentials Log full stack trace to telemetry, redact internals, return isError: true with "Tool temporarily unavailable (ref: <trace_id>); do not retry this tool", and trip the tool circuit breaker.

Output Shaping & Context Protection

Never dump raw database rows, full HTML pages, or multi-megabyte command outputs into tool_result:

  • Project and paginate: Return only the fields required for the task, plus pagination cursors (next_cursor, total_matching, truncated: true).
  • Deterministic truncation: If a tool output exceeds maxOutputBytes (e.g., 32 KB), store the full payload as an addressable artifact/resource and return a structured summary (head, tail, byte/line counts, and instructions on how to query specific ranges).
  • Idempotency & dry-run support: For mutating tools, accept an optional dry_run flag or return a preview diff when blast radius is high, and derive a deterministic idempotency key from (run_id, tool_call_id) before calling external APIs.

Csomagban lévő fájlok 1

  • SKILL.md