Skip to main 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
// @doctest id="20d9"

​
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));
// @doctest id="9841"

​
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);
// @doctest id="e190"

​
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
// @doctest id="c858"