Skip to content

Basic Concepts

AgentLoop

The orchestrator. Runs a step-based loop: call LLM, execute tools, check stop conditions, repeat.

BeforeExecution -> [ BeforeStep -> UseTools -> AfterStep -> ShouldStop? ] -> AfterExecution

AgentState

Immutable value object holding everything about an agent's session and execution.

Session data (persists across executions): - agentId - unique identifier - context - messages, system prompt, metadata - budget - resource limits (steps, tokens, time)

Execution data (transient, null between executions): - execution - current ExecutionState with steps, status, continuation signals

$state = AgentState::empty()
    ->withSystemPrompt('You are helpful.')
    ->withUserMessage('Hello')
    ->withBudget(new Budget(maxSteps: 10));

AgentContext

Holds the conversation data: messages, system prompt, metadata, and response format. The driver's CanCompileMessages compiler transforms the context into the final Messages sent to the LLM.

$state = AgentState::empty()
    ->withSystemPrompt('You are helpful.')
    ->withMetadata('user_id', 123);

AgentStep

An immutable snapshot of a single loop iteration:

  • inputMessages - what was sent to the LLM
  • outputMessages - tool results + assistant response
  • inferenceResponse - raw LLM response
  • toolExecutions - results of executed tools
  • stepType() - FinalResponse, ToolExecution, or Error

StepExecution

Wraps an AgentStep with timing and continuation data. Stored in the completed steps list after each iteration.

ExecutionState

Tracks the current execution's transient state: status, completed steps, current step, and continuation signals.

$state->execution()->status();        // ExecutionStatus::InProgress
$state->execution()->stepCount();     // 3
$state->execution()->shouldStop();    // false