Skip to content

use.md

Latest commit

 

History

History
140 lines (118 loc) · 7.26 KB

use.md

File metadata and controls

140 lines (118 loc) · 7.26 KB
Raw

Use Jentic One — agent patterns

You have a running install (install.md) and an approved identity. This file orients you; the authoritative, detailed playbook is the Jentic skill — skills/jentic/SKILL.md — which jentic skill init installs into your runtime's native layout (Claude/Cursor/Codex/…). Read that skill before driving real calls; this page is the map, not the territory.

The loop

Every task against an external API follows the same audited loop:

jentic access whoami                   # 1. what your bindings already SERVE
jentic catalog search "<capability>"   # 2. find an importable API (public catalog)
jentic catalog import <vendor/name>    #    import it into the local registry
jentic search "<what you want to do>"  # 3. find the operation — each hit gives its METHOD and URL
jentic inspect GET:https://api.example.com/v1/things/{id}     # 4. params, schemas, auth
jentic execute GET:https://api.example.com/v1/things/{id} --path id=abc   # 5. call it through the broker

Key behaviours (details and full flag syntax in the skill):

  • Decide access from whoami, don't probe with execute. If nothing you are bound to serves the API, file one composite jentic access request --provision <vendor/name> --auth … --rules-json … --reason … --wait covering the whole job. A human approves; you never approve yourself, and you never see the credential secret.
  • Import before search. A fresh registry is empty; search returning {"data": []} means nothing is imported, not that you lack access.
  • Denials teach you. A denied execute exits 2 and prints an agent_directive on stderr with the exact recovery (no_credential_binding, credential_not_provisioned, …). Follow its suggested_command; never re-send the same call.
  • The broker is a forward proxy: an execute target is always the operation's method plus its full upstream URL (METHOD:https://… — scheme, host, and path), never a host-relative path. Take the METHOD URL pair straight from the search hit; search only sees operations already imported into this instance's registry.

Rules for acting

  1. Never guess a command or flag. This CLI is not apt/npm/gh — commands like catalog --update or import do not exist. Before the first use of any command, run jentic <command> --help; every failure also prints the exact next command on stderr, so read the error before trying anything else.
  2. A freshly imported API has no credential. Your first access request for it must be --provision <vendor/name> (which describes the whole path: credential, rules, binding). A bare --api <vendor/name> request will be denied — nothing serves the API yet.
  3. Withdraw mistakes before re-filing. A new access request for the same target can be merged into your still-pending earlier request — so a --provision filed after a doomed --api can inherit its denial. If you filed a bad request, run jentic access withdraw <request_id> first, then file the correct one fresh.
  4. One composite request per job, always with --reason — never thrash with per-operation or duplicate requests.

How to do an action (worked example)

Task: "get the current Bitcoin price" on a fresh instance — nothing imported, no access yet.

# 1. What can I already call? (nothing yet, on a fresh install)
jentic access whoami

# 2. Find and import the API from the public catalog
jentic catalog search "crypto prices"
jentic catalog import coincap-io/coincap-io

# 3. First access request for a just-imported API: --provision, never --api
jentic access request --provision coincap-io/coincap-io \
  --auth api_key \
  --rules-json '[{"effect":"allow","methods":["GET"],"path":".*"}]' \
  --reason "read current crypto prices for the user" \
  --wait
# → a human fulfils and approves this in the dashboard; --wait blocks until they do.
#   Filed something wrong first? `jentic access withdraw <request_id>`, then re-file.

# 4. Find the operation — the hit gives you its METHOD and URL
jentic search "get current asset price"

# 5. Inspect, then execute with that exact METHOD + URL
jentic inspect GET:https://rest.coincap.io/v3/assets/{id}
jentic execute GET:https://rest.coincap.io/v3/assets/{id} --path id=bitcoin

If step 5 is denied (exit 2), the agent_directive on stderr names the exact recovery — follow its suggested_command instead of retrying the same call.

Machine-friendly behaviour

  • Add --json for machine-readable output. It exists on the leaf commands (search, execute, inspect, doctor, apis list, access status, …) — the bare group commands (jentic apis, jentic access) reject it. Do not rely on "non-TTY output is JSON automatically": jentic register persists mode: human in the context it creates, and an explicit mode short-circuits the TTY check, so piped output is prose on most installs. For a fully machine posture set JENTIC_MODE=agent — note it also deadlines most commands at 60 s (pass --timeout on long waits such as register and access request --wait).
  • Exit codes are a coarse contract: 0 ok, 1 transport/unexpected, 2 "cannot succeed as asked" (denial, resolve failure, missing context — do not blind-retry), 3 timed out still pending (retry later), 4 partially approved. Two caveats: execute exits 0 for any non-denial broker response, including 429 rate-limits, 503 shed/circuit responses and 504 timeouts — always check the HTTP status in the JSON envelope, never the exit code alone. Exit 1 is also broader than "transport": several deterministic, named-fix errors (e.g. MIGRATION_REQUIRED, NOT_AUTHENTICATED, PENDING_APPROVAL) also exit 1 — read the envelope's error.code and actionable_step before treating 1 as retryable.
  • Export JENTIC_SESSION_ID=<id> so operators can correlate your control-plane calls in the audit log (brokered execute calls land in Executions, which carries no session column); pass --idempotency-key <uuid> when retrying mutating calls.
  • jentic api <METHOD> <path> is an authenticated passthrough to any control-plane endpoint (jentic api ops lists them); full route/scope reference: endpoints.md.

What stays human

Action Where the human does it
Approve a new agent /app/agents in the console
Approve/fulfil access requests, enter credential secrets /app/access-requests in the console — hand them the request id, not the approve_url value (that URL is an API route, and its base is unset on most installs)
Create/manage users /app admin UI
Re-import an updated API spec (jentic catalog outdated) Their call — suggest it, never run it silently

Going deeper

  • First brokered call — worked end-to-end example
  • How credential resolution works — how a stored credential maps onto APIs
  • Overlays — fixing an imported spec without editing it
  • A running instance serves its own agent map at /llms.txt and interactive references at /app/docs — prefer those for anything runtime-specific.