Term
AgentRun
One agent's bounded assignment within exactly one WorkSession. An AgentRun may contain Turns and RunAttempts. This is the accepted term that replaces the ambiguous phrase "agent session".
Parent: WorkSession 1 via agent_runs
Purpose
Record the assignment, its outcomes, and the attempts and turns that fulfilled it, independently of which AgentInstance executed them.
Relationships
| Name | Target | Kind | Cardinality | Inverse |
|---|---|---|---|---|
work_session | WorkSession | assigns | 1 | agent_runs 0..* |
agent_profile | AgentProfile | references | 0..1 | assigned_runs 0..* |
run_attempts | RunAttempt | contains | 0..* | agent_run 1 |
turns | Turn | contains | 0..* | agent_run 1 |
tasks | Task | references | 0..* | agent_runs 0..* |
artifacts | Artifact | publishes | 0..* | produced_by_run 0..1 |
Lifecycle
Initial assigned. Terminal: succeeded, failed, cancelled.
assignedrunningblockedsucceededfailedcancelled
assigned→runningrunning→blockedblocked→runningrunning→succeededrunning→failedassigned→cancelledrunning→cancelledblocked→cancelledassigned→failed
Invariants
- MUST
exact-one-worksession: An AgentRun MUST belong to exactly one WorkSession. - MUST
children: An AgentRun MUST allow 0..* RunAttempts and 0..* Turns. - MUST NOT
instance-restart-stable: Replacing or restarting an AgentInstance MUST NOT change agent_run_id. - MUST NOT
not-agent-session: Implementations MUST NOT use unqualified "agent session" as the name of this entity. - MUST
policy-narrows: An AgentRun MUST only receive grants that narrow WorkSession policy.
Aliases
agent-assignment
Deprecated aliases
agent-sessionagent session
Not synonyms
- WorkSession: The session may contain many AgentRuns.
- AgentInstance: The instance executes attempts; it is not the assignment.
- RunAttempt: An attempt is one infrastructure execution of the run.
- Turn: A turn is one input-to-output cycle inside the run.
- Task: A task is a schedulable graph node and is not necessarily 1:1 with a run.
- HostConversation: Host chat is not an agent assignment.
Examples
- Assigning one reviewer agent to a WorkSession to produce a review Artifact.
Anti-examples
- Calling the host chat an "agent session".
- Re-identifying the assignment when the process is restarted.
Fields
The identity field is the index of the handle. fields is the exchange shape.
| Name | Kind | Type | Portable | Notes |
|---|---|---|---|---|
agent_run_id | identity | name | True | |
work_session_id | reference | name | True | |
agent_profile_id | reference | name | True | |
assigned_principal_id | reference | name | True |
Native mapping hooks
| System | Native term | Fidelity | Notes |
|---|---|---|---|
project-interop | _none_ | tbd |