Runtime lifecycle

This page defines the lifecycle terms used by agentcore. These are domain terms, not implementation types: a goroutine or channel may implement a lifecycle, but does not define its meaning.

Agent

An Agent owns conversation state, model configuration, tools, instructions and policy. It processes turns. An Agent is not a Session or a Task.

Session

A Session is the long-lived, bidirectional relationship between a caller and one Agent. It retains conversation state across multiple turns and owns the cancellation scope for work that may outlive an individual turn.

A Session begins at Scheduler.Spawn and ends when its parent context is cancelled, it is interrupted, or Session.Kill is called. Completing a turn does not end the Session.

Turn

A Turn begins with one user input and ends with a final agent response, an error, or cancellation. Agent.RunTurn implements this boundary. A Turn may contain multiple model calls and tool calls.

Only one Turn runs at a time within a Session. Conversation messages produced by a completed Turn remain available to later turns in the same Session.

Model call

A Model call is one request/response exchange with a model provider. The model may return a final response or request tools. A model call is a step inside a Turn, not a Turn itself.

Tool call

A Tool call is one invocation of Tool.Execute. Its context is bounded by the current Turn and the tool timeout. Synchronous work must stop when that context is cancelled.

Task and sub-agent

A Task is independently trackable work with its own completion and cancellation semantics. agentcore does not yet expose a general Task abstraction.

A sub-agent is an Agent created to perform a Task with isolated conversation state. An asynchronous sub-agent is owned by the parent Session, not by the shorter-lived Tool call that spawned it. Parent-result delivery and completed task retention are intentionally not standardized yet.

Ownership

Session
├── Turn
│   ├── Model call
│   └── Tool call
└── asynchronous sub-agent Task
    └── sub-agent Turn(s)

Cancellation flows down ownership edges. A Tool call timeout must not cancel an asynchronous sub-agent after it has been accepted by the parent Session.

Deliberately undefined

The runtime currently has no Harness interface, profile registry, general Task registry or observability schema. Those boundaries require at least two real integrations before their common contract can be known.