Term
RunAttempt
One infrastructure execution attempt for an AgentRun. Failures, retries, and instance replacements produce new RunAttempts under the same AgentRun.
Parent: AgentRun 1 via run_attempts
Purpose
Separate retry and crash semantics from the logical assignment so an AgentRun can survive executor replacement.
Relationships
| Name | Target | Kind | Cardinality | Inverse |
|---|---|---|---|---|
agent_run | AgentRun | references | 1 | run_attempts 0..* |
agent_instance | AgentInstance | references | 0..1 | run_attempts 0..* |
Lifecycle
Initial queued. Terminal: succeeded, failed, cancelled.
queuedrunningsucceededfailedcancelled
queued→runningrunning→succeededrunning→failedqueued→cancelledrunning→cancelledqueued→failed
Invariants
- MUST
belongs-to-run: A RunAttempt MUST belong to exactly one AgentRun. - MUST
instance-replaceable: A later RunAttempt MAY be executed by a different AgentInstance than an earlier one. - MUST NOT
not-the-run: A RunAttempt MUST NOT replace the AgentRun identity.
Aliases
execution-attempt
Deprecated aliases
None.
Not synonyms
- AgentRun: The run is the assignment; the attempt is one try at executing it.
- Turn: Turns are conversational or control cycles, not infrastructure launches.
- AgentInstance: The instance is the executor, not the attempt record.
Examples
- Retrying a failed launch on a replacement AgentInstance under the same agent_run_id.
Anti-examples
- Minting a new AgentRun because the process crashed.
Fields
The identity field is the index of the handle. fields is the exchange shape.
| Name | Kind | Type | Portable | Notes |
|---|---|---|---|---|
run_attempt_id | identity | name | True | |
agent_run_id | reference | name | True | |
agent_instance_id | reference | name | False | |
failure_class | metadata | string | True |
Native mapping hooks
| System | Native term | Fidelity | Notes |
|---|---|---|---|
project-interop | _none_ | tbd |