Move a custom agent to SDK v2
Jaah runs only agents built on SDK v2. A custom agent registered on SDK v1 stays on the Custom agents
tab, but it is marked Unsupported, its row says Re-register on SDK v2, and it can't run: it is no
longer offered in a task's Agent field, and a task that already picked it fails to start with
[agent_unrunnable]. Moving the same agent to SDK v2 keeps its name, its environment variables and the
projects and tasks that point at it.
Who can do this: changing an agent needs the permission to edit agents; without it, its page says You can view this agent but not edit it. You also need push access to the agent's repository.
-
In the sidebar, select Settings, then Agents under Customize, then the Custom agents tab. Find each row marked Unsupported with Re-register on SDK v2.

-
Select the agent's name. Its page shows Built on SDK v1. Re-register on SDK v2. Note its Repository URL, Sub-path and Ref on the Agent tab: that is the folder and the branch, tag or commit you change next.
-
In that folder of the repository, port the agent to SDK v2. An SDK v2 agent is an ACP agent: follow Build an agent with the SDK for the code. In its manifest, set
manifestto2, name the program to run incommand, and drop the SDK v1 fieldsentrypoint,sdkandinstall. Keepnameas it was, so the agent keeps its place in Jaah. The folder carries the SDK and lists its packages; every rule is in the Agent SDK reference. -
Push the change to the branch or tag that Ref names. If Ref is a fixed commit, type the new commit in Ref and select Save.
-
Select More, then Refresh. Jaah checks the folder at once instead of within about 15 minutes. A note says Refreshed and the agent's name, or names what still fails: fix that in the repository, push, and refresh again.
-
Check the mark beside the agent's name. Active, with no warning, means Jaah pinned the new commit: the Facts line under Details names it. The Unsupported mark is gone.
-
Start one task on it to try it: pick it in the task's Agent field, or leave Default where it is the project's default agent. A task that failed to start while the agent was unsupported can be restarted, as in Stop, restart or reset a task.
If you would rather start clean, register the SDK v2 code as a new agent with Add agent, then move its users over and delete the old one, as in Delete an agent that is still in use.
Related
- How agents work: what a refresh pins and every mark on the Custom agents tab.
- Fix a custom agent whose refresh failed: read and fix any other refresh failure.
- Change or remove a custom agent: change its ref or folder, disable or delete it.