Repository navigation
Tasks: add a session ID for lineage tracking and trajectory collection #542
Description
A task in AX stands alone. metadata has a name, atespace and create time, and status.id
identifies one task, but nothing ties together the tasks that make up one piece of work. In
practice, one piece of work often spans several tasks:
- an agent splits a job into subtasks, and those subtasks create more tasks;
- a failed task is retried, or rerun with a different prompt, image or model;
- a pipeline runs stages one after another (plan, implement, test, review), each in its own
task; - one user request fans out to several agents that run in parallel.
Without a shared ID:
- Lineage is lost. There's no way to answer "which tasks came from this request?" or "what
produced this task?". Names can carry a convention, but nothing enforces it and every client
invents its own. - Trajectories can't be put back together. Collecting a trajectory for evaluation, debugging
or training means joining each task's prompts, tool calls, model responses, commands and
results in order. Runners and the telemetry backends they send to have no common key to join
on, so the pieces stay scattered across tasks. - Clients can't group tasks.
ax get tasksand UIs such as AX Studio can only list tasks
flat. They can't show one session's tasks together, or clean them up together.
Proposal
Add a session ID that the creator sets when creating a task. AX stores it and passes it to the
task, but doesn't interpret it.
message TaskSpec {
// ... existing fields 1-7 ...
// session_id groups tasks that belong to one logical piece of work, such
// as an agent run and the subtasks it creates, or a task and its retries.
// AX stores it and exposes it to the runner, but does not interpret it.
// If empty, AX sets it to the task's ID, so every task belongs to a
// session. Immutable after creation.
string session_id = 8;
}
Rules:
- Set by the creator. The client that creates the task picks the session, whether that's a
user, a CLI, a pipeline or an agent inside another task. A task that creates subtasks passes
its ownsession_idon so they join its session. - Defaults to the task's ID. If it's unset, AX sets it to
status.id, so a task created on
its own starts a new session and every task can be grouped. - Immutable. It can't change after creation, so lineage can't be rewritten.
- Treated as opaque. AX validates only its length and character set (e.g. at most 128
characters,[A-Za-z0-9._:-]), so an external trace or run ID can be used directly. - Not secret. Like
spec.config, it's stored in plain text and shown byax get task.
Passing it to the task
- Environment: the runner sets
AX_SESSION_IDin the task command's environment, next to
AX_TASK_YAMLandAX_METADATA_URL. - Metadata: the metadata endpoint returns it with the rest of the task.
- Telemetry: runners attach it to logs, traces and model calls as
session.id, the
OpenTelemetry semantic-convention attribute. Telemetry and trajectory stores can then join
every task's records on that key.
Listing and cleanup
- Filtering:
ax get tasks --session <id>lists one session's tasks; the server API takes
the same filter. - Output:
ax get taskshowsSESSION(e.g. in-o wide). - Cleanup (optional):
ax delete tasks --session <id>deletes a whole session.
Example
An agent in task planner-1a2b splits the work and creates two subtasks, passing its session
on:
apiVersion: ax.io/v1alpha1
kind: Task
metadata:
name: implement-3c4d
spec:
sessionId: 9f2e7c1a-planner
image: ...
$ ax get tasks --session 9f2e7c1a-planner
NAME SESSION PHASE AGE
planner-1a2b 9f2e7c1a-planner Running 6m
implement-3c4d 9f2e7c1a-planner Running 4m
test-5e6f 9f2e7c1a-planner Pending 1m
Each runner tags its telemetry with session.id=9f2e7c1a-planner, so the full trajectory
across all three tasks can be collected with one query.
Alternatives considered
- Name prefixes: nothing enforces the convention, names are limited in length, and renaming
breaks the grouping. - Putting it in
spec.config: the field is runner-specific and AX doesn't interpret it, so
the server can't filter on it and other runners won't know where to find it. - Tracking sessions outside AX: every client and telemetry pipeline has to keep its own
mapping from tasks to sessions, which drifts and isn't visible inax get tasks.
Activity
rakyll commentedon Nov 2, 2026
Another option here is to explore hierarchical lineage with a reference to
parent_task. Evaluate the options before implementing.