Build an agent with the SDK
In this tutorial you build a small agent that says hello, uploads a report and ends its task, then run it on a real task. It takes about fifteen minutes. The steps are the same for a real agent: only what your code does in the middle changes.
You need:
- a GitHub repository you can push to, readable by the GitHub account you connected to Jaah;
- permission to edit agents and tasks in your organization, and a project with an Ubuntu node to run on — SDK agents run on Ubuntu nodes only for now;
- a checkout of the Jaah Agent SDK, to add it to your agent (step 3).
An SDK agent is an Agent Client Protocol (ACP) agent: you write one prompt handler, and the SDK speaks
the protocol and Jaah's extension to it, in Python (jaah_agent) or TypeScript (@jaah/agent-sdk). What
the packages offer is in the SDK reference.
1. Write the manifest
At the root of the repository, create jaah-agent.toml:
[agent]
manifest = 2 # SDK v2
name = "hello-agent" # lowercase letters, digits, hyphens; unique in your org
display_name = "Hello agent" # shown everywhere in Jaah
description = "Says hello, writes a report, settles the task."
type = "non_coding" # coding | non_coding | cli_wrapper
language = "python" # python | typescript
command = ["python3", "agent.py"] # run from the agent root
version = "0.1.0"
maintainer = "@your-github-handle" # or "Name <email>"
personas = ["coder"] # the kinds of task it may run
For a TypeScript agent, set language = "typescript" and command = ["node", "agent.mjs"]. Every field
is explained in the manifest reference.
2. Write the agent
The task arrives as the agent's first prompt. The agent answers in the turn and settles the task.
Python — agent.py
import html
import os
import jaah_agent
class Hello(jaah_agent.Agent):
name = "hello-agent"
version = "0.1.0"
async def prompt(self, turn: jaah_agent.Turn) -> None:
await turn.say("Hello from Hello agent!")
# Upload a report on EVERY path that settles: some kinds of task refuse a settle without one.
report = os.path.join(os.environ["JAAH_REPORT_DIR"], "report.html")
with open(report, "w", encoding="utf-8") as fh:
fh.write(f"<!doctype html><title>Hello</title><p>Hello! The task: {html.escape(turn.text[:200])}</p>")
await turn.jaah.call("artifact.upload", {"kind": "report", "path": report})
await turn.complete("Said hello and uploaded a report.", terminal_type="no_pr",
no_pr_reason="no_code_needed", no_pr_evidence="Hello agent: writes a report, no code.")
if __name__ == "__main__":
jaah_agent.run(Hello())
TypeScript — agent.ts
import { writeFileSync } from "node:fs";
import { join } from "node:path";
import { run, type Turn } from "@jaah/agent-sdk";
const esc = (s: string) => s.replace(/[&<>"]/g, (c) => ({ "&": "&", "<": "<", ">": ">", '"': """ })[c]!);
run({
info: { name: "hello-agent", version: "0.1.0" },
async prompt(turn: Turn) {
await turn.say("Hello from Hello agent!");
// Upload a report on EVERY path that settles: some kinds of task refuse a settle without one.
const report = join(process.env.JAAH_REPORT_DIR!, "report.html");
writeFileSync(report, `<!doctype html><title>Hello</title><p>Hello! The task: ${esc(turn.text.slice(0, 200))}</p>`);
await turn.jaah.call("artifact.upload", { kind: "report", path: report });
await turn.complete("Said hello and uploaded a report.", "no_pr", {
no_pr_reason: "no_code_needed", no_pr_evidence: "Hello agent: writes a report, no code." });
},
});
The manifest runs agent.mjs: step 3 bundles agent.ts and the SDK into it. Beside agent.ts, add a
package.json that lists the dependencies of the SDK, and create its package-lock.json with
npm install:
{
"name": "hello-agent",
"private": true,
"type": "module",
"dependencies": { "@agentclientprotocol/sdk": "^1.9.0", "zod": "^4.6.7" }
}
What the code does: say posts a message to the session, turn.text is the prompt — the task —
and artifact.upload puts the report on the task's Artifacts tab. complete settles the task, which
ends the run, so it comes last.
Upload a report on every path that settles. A researcher, business analysis, architecture, plan or finish task refuses a settle that comes without its deliverable (see Ending the task); for a coder task it is optional.
3. Add the SDK
The agent's folder carries the SDK and the list of packages it depends on (what the folder
carries); you commit no third-party code. The script
examples/vendor.py in the Agent SDK generates these files. In the SDK checkout, run
./check.sh once — it installs and builds what vendor.py uses — then:
.venv/bin/python examples/vendor.py /path/to/your/agent
- Python: it copies
jaah_agentbesideagent.pyand writesrequirements.txt— the SDK dependencies, each pinned to an exact version and hash. - TypeScript: it writes
agent.mjs—agent.tsand the SDK bundled into one file. The SDK dependencies stay outside it, installed from yourpackage-lock.json.
Commit the manifest, your code and the generated files, and push them to GitHub. Run vendor.py again
whenever you update the SDK.
To run your agent locally the same way, install the packages first:
.venv/bin/python examples/vendor.py --install /path/to/your/agent.
4. Register the agent
- In the console, open Settings, then Agents under Customize, then the Custom agents tab.
- Select Add agent.
- Enter the Repository URL — the address you open the repository at on GitHub. Leave Sub-path
empty when the manifest is at the repository root; otherwise enter the folder that holds it. Enter the
Ref — the branch, tag or commit to use,
mainby default. Jaah reads the repository with your own Git connection, the one under Settings › Personal › Git. - Optionally add Environment variables on the Environment tab — for example
JAAH_CODEX_MODELto change a connector's default model. They are set on every run of this agent. They are not for secrets: a name ending in_TOKEN,_API_KEY,_SECRETorPASSWORDis refused — use a credential. - Select Register. Jaah fetches the repository and checks the manifest, which takes a few seconds. If anything is wrong, each problem is listed on the page in a sentence that says what to fix — fix it, push, and register again. A folder that skipped step 3 is refused: its script imports the SDK without the files step 3 generates.
Hello agent now appears on the Custom agents tab with its version and the commit it is pinned to. When you push a change later, Jaah picks it up within about 15 minutes; to pick it up at once, open the agent's menu and select Refresh.
5. Pick it on a task
- Start a new task in a project with an Ubuntu node, and select
Advanced. Leave the persona as the default coder — the manifest's
personasnamescoder. - In the Agent field, choose Hello agent under Your agents & catalog. An agent that cannot run this task is shown greyed out with the reason.
- Start the task.
To have every coder task in a project run your agent without picking it, set it as the project's Default agent instead, in the project's settings.
6. Watch it run
When a node picks up the task:
- The run's session under Audit, Sessions shows Hello from Hello agent!.
- The task ends as done, with the summary "Said hello and uploaded a report." and the report on its Artifacts tab.
If the task fails instead, its reason starts with a code in brackets, such as [agent_unrunnable] or
[bundle_unavailable] — look it up in the failure codes.
Next steps
- Replace the middle of
promptwith your agent's real work. A coding agent works in the task's checkout —turn.cwd— opens a pull request and settles withmerged_pronce it is merged. - Read How agents work for the security gate and the rules every agent follows, and the Agent SDK reference for every call.