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]
| Field | Required | What it holds |
|---|---|---|
manifest | Yes | 2. Missing or any other value is refused. |
name | Yes | The agent's slug: 2 to 40 lowercase letters, digits or hyphens, starting with a letter. Unique in your organization. |
display_name | Yes | The name shown everywhere in Jaah, 1 to 60 characters. |
description | No | What the agent does, at most 280 characters. |
type | Yes | coding, non_coding or cli_wrapper (an agent that wraps a command-line tool). |
language | Yes | python or typescript. |
command | Yes | The 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. |
version | Yes | The agent's own semantic version, such as 1.2.0. |
maintainer | Yes | A GitHub handle such as @octocat, or Name <email>. |
personas | Yes | The 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_agentandrequirements.txt, every package pinned to a version and hash. The node installs it withpip install --require-hashes --only-binary=:all:, so each package must ship a wheel. - TypeScript: a script bundled with the SDK, and a
package.jsonlisting the dependencies of the SDK underdependencies, with itspackage-lock.json. The node installs it withnpm 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.
| Python | TypeScript | What 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.prompt | same | The prompt's text, and its raw ACP content blocks. |
turn.session_id, turn.cwd, turn.meta | sessionId, cwd, meta | The session; cwd is the task's checkout; meta is the run context Jaah sends with the session. |
await turn.say(text), think(text) | same | Posts a message, or a thought, to the session. |
await turn.update(update) | same | Posts 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) | same | Gives up on the task, instead of complete. Only for what no person could have cleared. |
| return a stop reason | resolve one | Ends the turn; nothing means end_turn. |
| the handler is cancelled | turn.signal aborts | The 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.
| Python | TypeScript | What it does |
|---|---|---|
jaah.available, jaah.supports(verb) | same | Whether 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() | same | The credentials this task may use: each one's name, type and description. No secrets. |
await jaah.credential(name) | same | One 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, includingautonomous— true when the task is Full Auto.artifact.uploadwithkindandpath: uploads a deliverable to the task's Artifacts tab —report,prd,architectureorfile. Write it under the directory inJAAH_REPORT_DIR.task.readandtask.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:
coderandresearcher:merged_pr, withpr_url, once the agent saw its pull request merged; orno_pr, withno_pr_reasonandno_pr_evidence, when the work needed no pull request. The reason is one ofduplicate,already_shipped,no_code_neededorremediated; the evidence says what the agent checked and found. A task in a folder rather than a repository takes onlyoutcome.business_analysisandarchitecture:analysis.planandfinish: 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
| Error | Meaning | Retry? |
|---|---|---|
ExtensionUnavailable | Jaah did not offer that call for this task. Nothing was sent. | No. |
ExtensionError | Jaah 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. |
AlreadySettled | The 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.
| Code | What happened | What 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. |