Skip to main content

​
Agents Package Cheatsheet

Root namespace: Cognesy\Agents This file is a quick, code-aligned map of the package surface. For narrative guidance and examples, use packages/agents/docs/*.md.

​
1. Core Loop

  • AgentLoop (readonly)
    • main orchestrator, implements CanControlAgentLoop and CanAcceptEventHandler
    • key API: default(), execute(), iterate()
    • accessors: tools(), toolExecutor(), driver(), eventHandler(), interceptor()
    • composition API: withTool(), withTools(), withDriver(), withToolExecutor(), withInterceptor(), withEventHandler(), with()
    • event API: wiretap(), onEvent()
    • note: terminal executions are auto-reset on entry to execute() / iterate()
  • CanControlAgentLoop
    • contract: execute(AgentState): AgentState, iterate(AgentState): iterable

​
2. State Model

  • Data\AgentState
    • immutable runtime state
    • factories: empty(), fromArray()
    • identity: agentId(), parentAgentId(), llmConfig(), executionCount(), createdAt(), updatedAt()
    • common mutators: withUserMessage(string|\Stringable|Message), withSystemPrompt(string|\Stringable), withMetadata(), withMessages(), withMessageStore(), withLLMConfig(), with()
    • step mutators: withCurrentStep(), withCurrentStepCompleted(), withExecutionCompleted(), withExecutionContinued()
    • stop/failure: withStopSignal(), withFailure(), withExecutionStatus()
    • context access: context(), store(), messages(), metadata()
    • result access: finalResponse(), currentResponse(), hasFinalResponse()
    • execution access: execution(), status(), stepCount(), steps(), usage(), errors(), hasErrors()
    • last-step accessors: lastStep(), lastStepExecution(), lastStepToolExecutions(), lastToolExecution(), lastStepErrors(), lastStepType(), lastStepUsage(), lastStepDuration(), lastStopSignal(), lastStopReason(), lastStopSource()
    • control: shouldStop(), forNextExecution()
    • serialization: debug(), toArray(), fromArray()
  • Data\ExecutionState
    • per-execution transient state (executionId, status, steps, continuation)
  • Data\AgentStep
    • one loop step snapshot (inputMessages, outputMessages, inferenceResponse, toolExecutions, errors)
  • Data\StepExecution
    • completed step wrapper with timing
  • Data\ToolExecution
    • one executed tool call (value(), hasError(), errorAsString(), wasBlocked())
  • Data\ExecutionBudget
    • optional limits: maxSteps, maxTokens, maxSeconds, maxCost, deadline
    • factories: unlimited()
    • queries: isEmpty(), isExhausted()
  • Data\AgentId, Data\ExecutionId, Data\AgentStepId, Data\ToolExecutionId
    • typed ID value objects

​
3. Enums

  • Enums\ExecutionStatus — Pending, InProgress, Completed, Stopped, Failed
  • Enums\AgentStepType — ToolExecution, FinalResponse, Error

​
4. Collections

  • Collections\Tools
    • immutable named tool collection
    • key API: has(), get(), names(), all(), count(), isEmpty(), descriptions(), withTool(), withTools(), withToolRemoved(), merge(), toToolSchema(): ToolDefinitions
  • Collections\AgentSteps
  • Collections\StepExecutions
  • Collections\ToolExecutions
  • Collections\NameList

​
5. Tools

​
Contracts

  • Tool\Contracts\ToolInterface
    • use(mixed ...$args): Result
    • toToolSchema(): ToolDefinition
    • descriptor(): CanDescribeTool
  • Tool\Contracts\CanDescribeTool
    • name(), description(), metadata(), instructions()
  • Tool\Contracts\CanExecuteToolCalls
    • executeTools(ToolCalls, AgentState): ToolExecutions
  • Tool\Contracts\CanAccessAgentState
  • Tool\Contracts\CanAccessToolCall
  • Tool\Contracts\CanManageTools

​
Base classes

  • Tool\Tools\SimpleTool
  • Tool\Tools\ReflectiveSchemaTool
  • Tool\Tools\FunctionTool
  • Tool\Tools\StateAwareTool
  • Tool\Tools\BaseTool
  • Tool\Tools\ContextAwareTool
  • Tool\Tools\FakeTool

​
Runtime

  • Tool\ToolExecutor
  • Tool\ToolRegistry
  • Tool\ToolDescriptor

​
6. Drivers

  • Drivers\CanUseTools
  • Drivers\CanAcceptToolRuntime
  • Drivers\ToolCalling\ToolCallingDriver (default)
  • Drivers\ToolCalling\ToolExecutionFormatter
  • Drivers\ReAct\ReActDriver
  • Drivers\Testing\FakeAgentDriver
  • Drivers\Testing\ScenarioStep

​
7. Context

  • Context\AgentContext
  • Context\CanCompileMessages
  • Context\CanAcceptMessageCompiler
  • Context\ContextSections
Compilers:
  • Context\Compilers\ConversationWithCurrentToolTrace (default)
  • Context\Compilers\AllSections
  • Context\Compilers\SelectedSections

​
8. Continuation / Stop

  • Continuation\StopReason
  • Continuation\StopSignal
  • Continuation\StopSignals
  • Continuation\ExecutionContinuation
  • Continuation\AgentStopException

​
9. Hooks / Interception

  • Hook\Contracts\HookInterface
  • Hook\Data\HookContext
  • Hook\Data\RegisteredHook
  • Hook\Collections\RegisteredHooks
  • Hook\Enums\HookTrigger
    • values: BeforeExecution, BeforeStep, BeforeToolUse, AfterToolUse, AfterStep, OnStop, AfterExecution, OnError
  • Hook\Collections\HookTriggers
  • Hook\HookStack
Built-in hooks:
  • Hook\Hooks\CallableHook
  • Hook\Hooks\StepsLimitHook
  • Hook\Hooks\TokenUsageLimitHook
  • Hook\Hooks\ExecutionTimeLimitHook
  • Hook\Hooks\FinishReasonHook
  • Hook\Hooks\ApplyContextConfigHook
Interception:
  • Interception\CanInterceptAgentLifecycle
  • Interception\PassThroughInterceptor

​
10. Builder / Capabilities

  • Builder\AgentBuilder
  • Builder\AgentConfigurator
  • Builder\Contracts\CanProvideAgentCapability
  • Builder\Contracts\CanConfigureAgent
  • Builder\Contracts\CanComposeAgentLoop
  • Builder\Contracts\CanProvideDeferredTools
  • Builder\Collections\DeferredToolProviders
  • Builder\Data\DeferredToolContext
Capability registry:
  • Capability\AgentCapabilityRegistry
  • Capability\CanManageAgentCapabilities
Core capabilities:
  • Capability\Core\UseLLMConfig
  • Capability\Core\UseGuards
  • Capability\Core\UseTools
  • Capability\Core\UseToolFactory
  • Capability\Core\UseHook
  • Capability\Core\UseDriver
  • Capability\Core\UseDriverDecorator
  • Capability\Core\UseContextCompiler
  • Capability\Core\UseContextCompilerDecorator
  • Capability\Core\UseContextConfig
  • Capability\Core\UseReActConfig
Domain capabilities:
  • Capability\Bash\UseBash
  • Capability\File\UseFileTools
    • installs: read_file, write_file, edit_file
    • standalone file tools also available: SearchFilesTool, ListDirTool
  • Capability\Metadata\UseMetadataTools
  • Capability\Subagent\UseSubagents
  • Capability\PlanningSubagent\UsePlanningSubagent
  • Capability\StructuredOutput\UseStructuredOutputs
  • Capability\Summarization\UseSummarization
  • Capability\SelfCritique\UseSelfCritique
  • Capability\Skills\UseSkills
  • Capability\Tasks\UseTaskPlanning
  • Capability\Tools\UseToolRegistry
  • Capability\ExecutionHistory\UseExecutionHistory
  • Capability\Retrospective\UseExecutionRetrospective
  • Capability\Broadcasting\UseAgentBroadcasting

​
11. Broadcasting

  • Broadcasting\AgentEventBroadcaster
  • Broadcasting\AgentBroadcastObserver
  • Broadcasting\BroadcastConfig
  • Broadcasting\CanBroadcastAgentEvents

​
12. Templates

  • Template\Data\AgentDefinition
    • core fields: name, description, systemPrompt, label, llmConfig, capabilities, tools, toolsDeny, skills, budget, metadata
    • tool semantics: tools === null means inherit all available tools
  • Template\AgentDefinitionLoader
  • Template\AgentDefinitionRegistry
  • Template\Contracts\CanManageAgentDefinitions
  • Template\Contracts\CanInstantiateAgentLoop
  • Template\Contracts\CanInstantiateAgentState
  • Template\Parsers\CanParseAgentDefinition
  • Template\Factory\DefinitionStateFactory
  • Template\Factory\DefinitionLoopFactory
  • parsers: Template\Parsers\MarkdownDefinitionParser, JsonDefinitionParser, YamlDefinitionParser

​
13. Sessions

Core:
  • Session\Data\SessionId
  • Session\Data\AgentSessionInfo
  • Session\Data\AgentSession
    • access: info(), definition(), state(), sessionId(), status(), version()
  • Session\SessionFactory
  • Session\SessionRepository
  • Session\SessionRuntime
Contracts:
  • Session\Contracts\CanManageAgentSessions
  • Session\Contracts\CanExecuteSessionAction
  • Session\Contracts\CanStoreSessions
  • Session\Contracts\CanControlAgentSession
Stores:
  • Session\Store\InMemorySessionStore
  • Session\Store\FileSessionStore
Actions:
  • Session\Actions\SendMessage (accepts string|\Stringable|Message)
  • Session\Actions\ForkSession (returns a new branch session object; persist via repository create())
  • Session\Actions\ResumeSession
  • Session\Actions\SuspendSession
  • Session\Actions\ClearSession
  • Session\Actions\ChangeModel
  • Session\Actions\ChangeSystemPrompt (accepts string|\Stringable)
  • Session\Actions\WriteMetadata
  • Session\Actions\UpdateTask
Enums:
  • Session\Enums\SessionStatus — Active, Suspended, Completed, Failed, Deleted
  • Session\Enums\AgentSessionStage — AfterLoad, AfterAction, BeforeSave, AfterSave
Session hooks:
  • Session\SessionHookStack
  • Session\RegisteredSessionHook
  • Session\PassThroughSessionController
  • Session\Collections\SessionInfoList
Exceptions:
  • Session\Exceptions\SessionNotFoundException
  • Session\Exceptions\SessionConflictException
  • Session\Exceptions\InvalidSessionFileException

​
14. Events

Agent events include:
  • AgentExecutionStarted, AgentStepStarted, AgentStepCompleted
  • AgentExecutionStopped, AgentExecutionCompleted, AgentExecutionFailed
  • AgentStateUpdated
  • ContinuationEvaluated, StopSignalReceived, TokenUsageReported
  • ToolCallStarted, ToolCallCompleted, ToolCallBlocked
  • InferenceRequestStarted, InferenceResponseReceived
  • SubagentSpawning, SubagentCompleted
  • HookExecuted, DecisionExtractionFailed, ValidationFailed
  • Events\AgentEvent (base class)
Event support:
  • Events\Support\AgentEventConsoleFormatter
  • Events\Support\AgentEventConsoleObserver
Session events include:
  • SessionLoaded, SessionActionExecuted, SessionSaved
  • SessionLoadFailed, SessionSaveFailed

​
15. Exceptions

  • Exceptions\AgentException (base)
  • Exceptions\AgentNotFoundException
  • Exceptions\InvalidToolException
  • Exceptions\InvalidToolArgumentsException
  • Exceptions\ToolCallBlockedException
  • Exceptions\ToolExecutionBlockedException
  • Exceptions\ToolExecutionException

​
16. Skills

  • Capability\Skills\Skill
    • immutable skill value object
    • standard fields: name, description, license, compatibility, metadata, allowedTools, body, path, resources
    • extension fields: disableModelInvocation, userInvocable, argumentHint, model, context, agent
    • key API: render(?string $arguments), renderMetadata(), toArray()
    • argument substitution: $ARGUMENTS, $ARGUMENTS[N], $N placeholders
  • Capability\Skills\SkillLibrary
    • discovers SKILL.md files in <path>/<skill-name>/SKILL.md
    • lazy-loads skill content on first access, caches result
    • key API: listSkills(modelInvocable, userInvocable), hasSkill(), getSkill(), renderSkillList()
    • resource discovery: scans scripts/, references/, assets/, examples/ subdirs
  • Capability\Skills\LoadSkillTool
    • tool exposed to LLM: load_skill(skill_name, list_skills, arguments)
    • user-invocable filtering on list mode
  • Capability\Skills\AppendSkillMetadataHook
    • injects skill names/descriptions as system message before first step
    • filters out disable-model-invocation: true skills
  • Capability\Skills\TrackActiveSkillHook
    • tracks active skill metadata (allowed-tools, model) in state after load_skill completes
  • Capability\Skills\SkillToolFilterHook
    • enforces allowed-tools restrictions; blocks non-allowed tools (except load_skill itself)
  • Capability\Skills\SkillModelOverrideHook
    • overrides LLMConfig when a skill with a model field is active
  • Capability\Skills\SkillForkExecutor
    • executes skills in a forked agent loop context
  • Capability\Skills\SkillPreprocessor
    • executes !command“ patterns in skill body before argument substitution
    • configurable working directory and timeout
    • opt-in: pass to UseSkills or LoadSkillTool constructor
  • Capability\Skills\UseSkills
    • capability that wires LoadSkillTool + hooks into agent
    • optional ?SkillPreprocessor for shell preprocessing
  • follows Agent Skills Open Standard (30+ tools)

​
17. Testing

  • Drivers\Testing\FakeAgentDriver
    • scripted loop steps via ScenarioStep
    • best for most deterministic agent-loop tests
  • Tests\Support\FakeInferenceDriver
    • queued raw InferenceResponse or streaming PartialInferenceDelta fixtures
    • use when the test sits closer to the inference boundary
  • Tool\Tools\FakeTool
    • deterministic tool double with fixed or callable-backed results
  • Tests\Support\FakeSubagentProvider
    • in-memory subagent definition registry for capability tests
  • Tests\Support\TestAgentLoop
    • small loop harness with explicit max-iteration stop behavior
  • Cognesy\Sandbox\Testing\FakeSandbox (from packages/sandbox, not agents)
    • deterministic process-execution seam for bash-backed tools

​
18. Docs Index

Read in this order:
  1. packages/agents/docs/01-introduction.md
  2. packages/agents/docs/testing-doubles.md
  3. packages/agents/docs/02-basic-agent.md
  4. packages/agents/docs/05-tools.md
  5. packages/agents/docs/06-building-tools.md
  6. packages/agents/docs/13-agent-builder.md
  7. packages/agents/docs/14-agent-templates.md
  8. packages/agents/docs/15-subagents.md
  9. packages/agents/docs/16-session-runtime.md
  10. packages/agents/docs/19-skills.md