Skip to content

chore(backend): Rename taskId -> agentTaskId #8013

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tmilewski wants to merge 3 commits into
base: main
Choose a base branch
from
Open

chore(backend): Rename taskId -> agentTaskId #8013

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
09d8ef9
chore(backend): Rename taskId -> agentTaskId
tmilewski Mar 9, 2026
10292ef
chore: Add changeset
tmilewski Mar 9, 2026
5c576d0
chore: Harden the output
tmilewski Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/cute-places-wear.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@clerk/backend': patch
---

Adds `agentTaskId` and deprecates `taskId` to Agent Tasks Create response.
10 changes: 6 additions & 4 deletions packages/backend/src/api/__tests__/AgentTaskApi.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ describe('AgentTaskAPI', () => {
const mockAgentTaskResponse = {
object: 'agent_task',
agent_id: 'agent_123',
task_id: 'task_456',
task_id: 'agent_task_456',
agent_task_id: 'agent_task_456',
url: 'https://example.com/agent-task',
};

Expand Down Expand Up @@ -51,9 +52,9 @@ describe('AgentTaskAPI', () => {
redirectUrl: 'https://example.com/callback',
sessionMaxDurationInSeconds: 1800,
});

expect(response.agentId).toBe('agent_123');
expect(response.taskId).toBe('task_456');
expect(response.taskId).toBe('agent_task_456');
expect(response.agentTaskId).toBe('agent_task_456');
expect(response.url).toBe('https://example.com/agent-task');
});

Expand Down Expand Up @@ -90,7 +91,8 @@ describe('AgentTaskAPI', () => {
});

expect(response.agentId).toBe('agent_123');
expect(response.taskId).toBe('task_456');
expect(response.taskId).toBe('agent_task_456');
expect(response.agentTaskId).toBe('agent_task_456');
});
});
});
8 changes: 7 additions & 1 deletion packages/backend/src/api/resources/AgentTask.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,13 @@ export class AgentTask {
readonly agentId: string,
/**
* A unique identifier for this agent task.
* @deprecated Use agentTaskId instead.
*/
readonly taskId: string,
/**
* A unique identifier for this agent task.
*/
readonly agentTaskId: string,
/**
* The FAPI URL that, when visited, creates a session for the user.
*/
Expand All @@ -29,6 +34,7 @@ export class AgentTask {
* @returns A new AgentTask instance
*/
static fromJSON(data: AgentTaskJSON): AgentTask {
return new AgentTask(data.agent_id, data.task_id, data.url);
const agentTaskId = data.agent_task_id ?? data.task_id ?? '';
return new AgentTask(data.agent_id, agentTaskId, agentTaskId, data.url);
}
}
4 changes: 4 additions & 0 deletions packages/backend/src/api/resources/JSON.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -516,6 +516,10 @@ export interface SignInTokenJSON extends ClerkResourceJSON {
export interface AgentTaskJSON extends ClerkResourceJSON {
object: typeof ObjectType.AgentTask;
agent_id: string;
agent_task_id: string;
/**
* @deprecated Use `agent_task_id` instead.
*/
task_id: string;
url: string;
Comment on lines 516 to 524
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Keep accepting task_id during the deprecation window.

Line 519 hard-renames the wire shape in a patch release, but the PR description says the old field is only deprecated. If an older API response still sends only task_id, AgentTask.fromJSON will populate both taskId and agentTaskId as undefined. Please keep the legacy key optional until the actual removal and fall back to it when agent_task_id is absent.

Proposed compatibility fix 
 export interface AgentTaskJSON extends ClerkResourceJSON {
   object: typeof ObjectType.AgentTask;
   agent_id: string;
-  agent_task_id: string;
+  /**
+   * `@deprecated` Use `agent_task_id` instead.
+   */
+  task_id?: string;
+  agent_task_id?: string;
   url: string;
 }
 static fromJSON(data: AgentTaskJSON): AgentTask {
-  return new AgentTask(data.agent_id, data.agent_task_id, data.agent_task_id, data.url);
+  const agentTaskId = data.agent_task_id ?? data.task_id;
+  return new AgentTask(data.agent_id, agentTaskId, agentTaskId, data.url);
 }
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@packages/backend/src/api/resources/JSON.ts` around lines 516 - 520,
AgentTaskJSON and AgentTask.fromJSON must remain backward-compatible with the
legacy task_id field: update the AgentTaskJSON interface to include an optional
legacy field (task_id?: string) and modify AgentTask.fromJSON to read
agent_task_id first and, if missing, fall back to task_id, populating the
internal agentTaskId (and any related getters) from whichever key is present;
ensure both keys are accepted during the deprecation window so older API
responses still produce a valid AgentTask instance.

}
Expand Down
Loading