Skip to main content

Agent SDK reference

An SDK agent is an Agent Client Protocol (ACP) agent. The Jaah Agent SDK comes as two packages with one set of calls: jaah_agent for Python and @jaah/agent-sdk for TypeScript. Python names are snake_case; TypeScript names are camelCase. You write one prompt handler; the SDK answers the rest of the protocol and makes Jaah's extension calls. The node provides no SDK: your agent's folder carries it (see How agents work). The SDK is private and is not published to PyPI or npm.

The manifest​

The manifest is the file jaah-agent.toml at the agent root: the repository root, or the sub-path you name when you register the agent. Jaah checks it when you register or refresh the agent.

[agent]​

FieldRequiredWhat it holds
manifestYes2. Missing or any other value is refused.
nameYesThe agent's slug: 2 to 40 lowercase letters, digits or hyphens, starting with a letter. Unique in your organization.
display_nameYesThe name shown everywhere in Jaah, 1 to 60 characters.
descriptionNoWhat the agent does, at most 280 characters.
typeYescoding, non_coding or cli_wrapper (an agent that wraps a command-line tool).
languageYespython or typescript.
commandYesThe command the node runs from the agent root, as a list of words, such as ["python3", "agent.py"] or ["node", "agent.mjs"]. The node runs python3 3.12 or later and Node 22.18 or later.
versionYesThe agent's own semantic version, such as 1.2.0.
maintainerYesA GitHub handle such as @octocat, or Name <email>.
personasYesThe kinds of task the agent may run, at least one of coder, business_analysis, architecture, plan, finish and researcher. A task whose persona is not listed never runs the agent.

What the folder carries​

The folder carries the SDK and lists the packages it depends on; it holds no third-party code. Before it starts command, the node installs the listed packages into the folder. When the script command runs imports the SDK, registration checks the folder has, beside the script:

  • Python: jaah_agent and requirements.txt, every package pinned to a version and hash. The node installs it with pip install --require-hashes --only-binary=:all:, so each package must ship a wheel.
  • TypeScript: a script bundled with the SDK, and a package.json listing the dependencies of the SDK under dependencies, with its package-lock.json. The node installs it with npm ci --omit=dev --ignore-scripts.

The node needs to reach pypi.org and files.pythonhosted.org, or registry.npmjs.org. The script examples/vendor.py in the Agent SDK generates these files (see Add the SDK).

Environment variables​

The variables set under Environment when you register the agent are set on its process. A name ending in _TOKEN, _API_KEY, _SECRET or PASSWORD is refused: fetch a secret as a credential.

The turn​

The node's ACP host starts the agent, opens one session and sends the task as the first prompt. Each prompt is one turn: the SDK calls your handler with a Turn. The agent reads ACP on standard input and writes it on standard output; anything it prints for people goes to standard error.

PythonTypeScriptWhat it does
jaah_agent.run(agent)run(agent)Serves the agent over standard input and output. In Python, agent subclasses jaah_agent.Agent and implements async prompt(turn); in TypeScript it is { info, prompt(turn) }.
turn.text, turn.promptsameThe prompt's text, and its raw ACP content blocks.
turn.session_id, turn.cwd, turn.metasessionId, cwd, metaThe session; cwd is the task's checkout; meta is the run context Jaah sends with the session.
await turn.say(text), think(text)samePosts a message, or a thought, to the session.
await turn.update(update)samePosts any ACP session update: tool calls, plans, usage.
await turn.complete(summary, terminal_type, **refs)complete(summary, terminalType, refs)The final call: settles the task (see Ending the task).
await turn.fail(reason)sameGives up on the task, instead of complete. Only for what no person could have cleared.
return a stop reasonresolve oneEnds the turn; nothing means end_turn.
the handler is cancelledturn.signal abortsThe turn was cancelled.

The agent's process starts in the agent root; the task's checkout is turn.cwd. If a turn ends with the task still open, the node prompts the agent once to finish and settle.

Usage​

Report each model call's tokens as an ACP usage_update whose _meta["jaah.ai"]["usage"] carries model, input_tokens, cache_read_tokens and output_tokens. Jaah prices them on the session's Efficiency view.

Extension calls​

turn.jaah makes Jaah's calls. Jaah offers the calls a task may make; one it does not offer raises ExtensionUnavailable and is never sent.

PythonTypeScriptWhat it does
jaah.available, jaah.supports(verb)sameWhether Jaah offered its extension, or one call.
await jaah.ask(question, options=…, header=…, multi_select=…)ask(question, {options, header, multiSelect})Asks a person one question (see Questions).
await jaah.credentials()sameThe credentials this task may use: each one's name, type and description. No secrets.
await jaah.credential(name)sameOne credential's configuration, secrets included. Never log it.
await jaah.credential_file(name)credentialFile(name)The same, written to a file only its owner can read, in a private directory; returns the path. Hand it to a tool this way, never in an environment variable. Settling removes the files.
await jaah.call(verb, params)call(verb, params)Any offered call, such as task.get, artifact.upload, task.read or task.search.

Useful calls through call:

  • task.get: this task, including autonomous — true when the task is Full Auto.
  • artifact.upload with kind and path: uploads a deliverable to the task's Artifacts tab — report, prd, architecture or file. Write it under the directory in JAAH_REPORT_DIR.
  • task.read and task.search: read or search other tasks in the project.

Questions​

A question has a question, optional options (each a string or a label and description), an optional header and multi_select. Omit options for a free-form answer. Asking ends the turn: the person's answer is the agent's next prompt.

Under Full Auto, Jaah accepts a question only when its header is Credential, Access, Human act, External or Guard — a blocker only a person can clear — and refuses any other.

Ending the task​

complete takes a short summary and one terminal type. Which ones a task may claim depends on its persona:

  • coder and researcher: merged_pr, with pr_url, once the agent saw its pull request merged; or no_pr, with no_pr_reason and no_pr_evidence, when the work needed no pull request. The reason is one of duplicate, already_shipped, no_code_needed or remediated; the evidence says what the agent checked and found. A task in a folder rather than a repository takes only outcome.
  • business_analysis and architecture: analysis.
  • plan and finish: endings of their own in the task pipeline.

Settling ends the run, so make it the last thing your agent does. Some kinds of task must upload a deliverable first — a researcher its report, a business analysis its requirements document — and a settle without it is refused. A refused settle leaves the task open: fix what it names and settle again.

Errors​

ErrorMeaningRetry?
ExtensionUnavailableJaah did not offer that call for this task. Nothing was sent.No.
ExtensionErrorJaah answered with an error: its code, message and data. A refusal names what to fix; unavailable means Jaah was not reached.A refusal: not unchanged — fix what it names. unavailable: yes, as sent.
AlreadySettledThe session already settled, or a settle is in flight.No.

Failure codes​

When a run cannot start, Jaah fails the task with a reason that starts with a code in brackets, followed by a sentence that says exactly what went wrong.

CodeWhat happenedWhat to do
[agent_unrunnable]The task's agent cannot run it: disabled, removed, not visible to your organization, an SDK v1 agent, never fetched, or it does not serve the task's persona.Enable or refresh the agent, re-register it on SDK v2, add the persona to its manifest, or pick another agent.
[bundle_unavailable]The node could not download the agent's pinned commit.Start the task again; refresh the agent if the commit no longer exists.
[bundle_corrupt]The agent's code on the node did not match the commit Jaah pinned.Refresh the agent and start the task again.
[agent_install_failed]The node could not install the packages the agent's folder lists.Check the node can reach PyPI or the npm registry and that every listed package exists, then start the task again.
[agent_env_refused]One of the agent's environment variables is named like a secret.Remove it under Edit, and fetch the secret as a credential.