Term
AgentInstance
A running process or remote endpoint capable of executing RunAttempts. An AgentInstance is not an assignment and is not a Principal.
Purpose
Name the live executor that performs attempts so that replacing or restarting it does not rewrite the AgentRun identity.
Relationships
| Name | Target | Kind | Cardinality | Inverse |
|---|---|---|---|---|
profile | AgentProfile | references | 0..1 | instances 0..* |
run_attempts | RunAttempt | executes | 0..* | agent_instance 0..1 |
principal | Principal | authenticates | 0..1 | agent_instances 0..* |
Lifecycle
Initial starting. Terminal: stopped, failed.
startingreadybusystoppingstoppedfailed
starting→readystarting→failedready→busybusy→readyready→stoppingbusy→stoppingstopping→stoppedready→failedbusy→failedstarting→stopping
Invariants
- MUST
many-attempts: An AgentInstance MAY execute many RunAttempts, including for different AgentRuns. - MUST NOT
restart-does-not-change-run: Replacing or restarting an AgentInstance MUST NOT change an AgentRun identity. - MUST NOT
not-an-assignment: An AgentInstance MUST NOT be treated as an AgentRun. - MUST NOT
not-a-principal: An AgentInstance MUST NOT be treated as the authenticated Principal.
Aliases
running-agent
Deprecated aliases
None.
Not synonyms
- AgentRun: The run is the assignment; the instance is the executor.
- AgentProfile: The profile is the kind; the instance is a live process or endpoint.
- Principal: Identity for auth is Principal; the instance is infrastructure.
Examples
- A local agent process that executes several RunAttempts and is then replaced.
- A remote agent endpoint that picks up attempts for more than one AgentRun.
Anti-examples
- The logical assignment "review PR 42" (that is an AgentRun or Task).
Fields
The identity field is the index of the handle. fields is the exchange shape.
| Name | Kind | Type | Portable | Notes |
|---|---|---|---|---|
agent_instance_id | identity | name | False | Instance identity is not required in portable project snapshots. |
agent_profile_id | reference | name | True | |
endpoint | descriptive | uri | False |
Native mapping hooks
| System | Native term | Fidelity | Notes |
|---|---|---|---|
project-interop | _none_ | tbd |