Skip to main content

​
Introduction

Agent templates let you define agents as data rather than PHP code. Instead of writing a class that constructs an AgentBuilder with hardcoded capabilities and tools, you describe the agent’s identity, instructions, tool access, and resource budget in a definition file. At runtime, a factory turns that definition into a working AgentLoop and AgentState. This separation between definition and instantiation makes it possible to manage agents through configuration files, version them alongside your prompts, and let non-developers create or adjust agents without touching PHP. It is also the foundation of the subagent system — when a parent agent spawns a child, it looks up the child’s AgentDefinition in a registry and builds a loop from it on the fly.

​
AgentDefinition

AgentDefinition is the core data object that describes an agent. It is a final readonly class with the following fields:
FieldTypeRequiredDescription
namestringYesUnique identifier used to look up the agent in registries
descriptionstringYesHuman-readable summary of what the agent does. Also shown in tool schemas when the agent is available as a subagent.
systemPromptstringYesThe system prompt that instructs the agent’s behavior
labelstring|nullNoDisplay name (defaults to name if omitted)
llmConfigLLMConfig|string|nullNoLLM configuration. Pass a string like 'anthropic' for just the driver name, or a full LLMConfig object for model-level control.
capabilitiesNameListNoNamed capabilities to activate (looked up in AgentCapabilityRegistry)
toolsNameList|nullNoAllow-list of tool names. null means inherit all available tools.
toolsDenyNameList|nullNoDeny-list of tool names to exclude from the inherited or allowed set
skillsNameList|nullNoNamed skills to inject into the agent’s context
budgetExecutionBudget|nullNoResource limits: max steps, tokens, seconds, cost, and deadline
metadataMetadata|nullNoArbitrary key-value data merged into the agent’s state

​
Creating Definitions in PHP

use Cognesy\Agents\Collections\NameList;
use Cognesy\Agents\Data\ExecutionBudget;
use Cognesy\Agents\Template\Data\AgentDefinition;
use Cognesy\Polyglot\Inference\Config\LLMConfig;

$definition = new AgentDefinition(
    name: 'researcher',
    description: 'Searches for information on a topic and summarizes findings',
    systemPrompt: 'You are a research assistant. Find and summarize information accurately.',
    label: 'Research Agent',
    llmConfig: LLMConfig::fromArray([
        'driver' => 'anthropic',
        'model' => 'claude-sonnet-4-20250514',
    ]),
    budget: new ExecutionBudget(maxSteps: 10, maxTokens: 8000),
    tools: new NameList('bash', 'read_file'),
    toolsDeny: new NameList('write_file'),
    capabilities: new NameList('use_bash'),
);
// @doctest id="d17d"

​
Tool Visibility Rules

The tools and toolsDeny fields work together to control which tools the agent can access:
  • tools: null (the default) — the agent inherits all tools available in its context. For subagents, this means all tools the parent has.
  • tools: new NameList('read_file', 'bash') — only these named tools are allowed. Any other tools are excluded.
  • toolsDeny: new NameList('write_file') — these tools are removed from whatever set the agent would otherwise have, whether inherited or explicitly allowed.
The deny list is applied after the allow list. If you set tools to allow read_file and write_file, and toolsDeny to deny write_file, the agent will only have access to read_file.

​
ExecutionBudget

The ExecutionBudget class defines resource limits for a single agent execution. All fields are optional — null means unlimited. 
use Cognesy\Agents\Data\ExecutionBudget;

$budget = new ExecutionBudget(
    maxSteps: 10,         // maximum number of agent loop iterations
    maxTokens: 8000,      // total token usage across all steps
    maxSeconds: 60.0,     // wall-clock time limit
    maxCost: 0.50,        // maximum cost in dollars
    deadline: new DateTimeImmutable('2025-12-31'),
);
// @doctest id="fa95"
When an AgentDefinition declares a budget, it is translated into UseGuards during loop instantiation.

​
Definition Files

Agent definitions can be stored in markdown, YAML, or JSON files. Each format maps directly to the AgentDefinition fields.

​
Markdown Format

Markdown definitions use YAML front matter for structured fields and the document body for the system prompt. This is the most readable format for agents with long or complex system prompts. 
---
name: researcher
description: Searches for information on a topic
label: Research Agent
llmConfig:
  driver: anthropic
  model: claude-sonnet-4-20250514
budget:
  maxSteps: 10
  maxTokens: 8000
tools:
  - bash
  - read_file
toolsDeny:
  - write_file
capabilities:
  - use_bash
metadata:
  domain: research
  version: "2.0"
---

You are a research assistant. Your job is to find and summarize information accurately.

When given a topic, use the available tools to gather evidence, then synthesize your findings
into a clear, well-structured summary. Always cite the sources you used.
// @doctest id="182e"
The document body (everything after the front matter) becomes the systemPrompt field.

​
YAML Format

name: researcher
description: Searches for information on a topic
systemPrompt: |
  You are a research assistant. Find and summarize information accurately.
  Always cite the sources you used.
llmConfig:
  driver: anthropic
budget:
  maxSteps: 10
  maxTokens: 8000
tools:
  - bash
  - read_file
# @doctest id="3ffd"

​
JSON Format

{
  "name": "researcher",
  "description": "Searches for information on a topic",
  "systemPrompt": "You are a research assistant. Find and summarize information accurately.",
  "llmConfig": {
    "driver": "anthropic"
  },
  "budget": {
    "maxSteps": 10,
    "maxTokens": 8000
  },
  "tools": ["bash", "read_file"]
}
// @doctest id="5a99"
All three formats produce identical AgentDefinition objects when loaded.

​
Loading Definitions

​
AgentDefinitionLoader

The AgentDefinitionLoader class parses a single file into an AgentDefinition. It selects the appropriate parser based on the file extension. 
use Cognesy\Agents\Template\AgentDefinitionLoader;

$loader = new AgentDefinitionLoader();
$definition = $loader->loadFile('/path/to/researcher.md');
// @doctest id="2831"
Supported extensions: .md, .json, .yaml, .yml. The loader throws a RuntimeException if the file cannot be read and an InvalidArgumentException for unsupported extensions. You can also supply custom parsers by passing an array to the constructor: 
use Cognesy\Agents\Template\Parsers\MarkdownDefinitionParser;
use Cognesy\Agents\Template\Parsers\JsonDefinitionParser;
use Cognesy\Agents\Template\Parsers\YamlDefinitionParser;

$loader = new AgentDefinitionLoader([
    'md' => new MarkdownDefinitionParser(),
    'json' => new JsonDefinitionParser(),
    'yaml' => new YamlDefinitionParser(),
    'yml' => new YamlDefinitionParser(),
]);
// @doctest id="4077"

​
AgentDefinitionRegistry

The AgentDefinitionRegistry is a named collection of agent definitions. It supports programmatic registration, file loading, directory scanning, and auto-discovery. 
use Cognesy\Agents\Template\AgentDefinitionRegistry;

$registry = new AgentDefinitionRegistry();
// @doctest id="e8ea"

​
Programmatic Registration

$registry->register($definition);
$registry->registerMany($def1, $def2, $def3);
// @doctest id="d8f8"

​
Loading from Files

// Load a single file
$registry->loadFromFile('/agents/researcher.md');

// Load all definition files from a directory
$registry->loadFromDirectory('/agents');

// Load recursively, scanning subdirectories
$registry->loadFromDirectory('/agents', recursive: true);
// @doctest id="1e24"
During directory scans, files that fail to parse are skipped rather than causing exceptions. The errors are collected and can be inspected afterward: 
$errors = $registry->errors();
// Returns: ['path/to/broken.md' => 'Error message', ...]
// @doctest id="b58d"

​
Auto-Discovery

The autoDiscover() method scans up to three standard locations for agent definition files: 
$registry->autoDiscover(
    projectPath: '/my/project',      // scans /my/project/.claude/agents
    packagePath: '/package/agents',   // scans this directory directly
    userPath: '/user/agents',         // scans this directory directly
);
// @doctest id="9a01"
Paths are scanned in order: userPath, packagePath, then projectPath/.claude/agents. Later registrations overwrite earlier ones with the same name, so user-level definitions take precedence over package defaults.

​
Querying the Registry

$definition = $registry->get('researcher');    // throws AgentNotFoundException if missing
$exists = $registry->has('researcher');        // returns bool
$names = $registry->names();                   // returns ['researcher', 'reviewer', ...]
$count = $registry->count();                   // returns int
$all = $registry->all();                       // returns ['name' => AgentDefinition, ...]
// @doctest id="7f39"

​
Instantiation Factories

Once you have an AgentDefinition, two factory classes turn it into runnable components: one for the initial AgentState, and one for the AgentLoop that executes it.

​
DefinitionStateFactory

Creates an AgentState pre-configured with the definition’s system prompt, metadata, and LLM config. It implements the CanInstantiateAgentState contract. 
use Cognesy\Agents\Template\Factory\DefinitionStateFactory;

$factory = new DefinitionStateFactory();
$state = $factory->instantiateAgentState($definition);
// @doctest id="47fa"
You can also pass a seed state to merge the definition’s settings onto an existing state: 
$existingState = AgentState::empty()->withUserMessage('Start here');
$state = $factory->instantiateAgentState($definition, seed: $existingState);
// @doctest id="36a8"
The factory applies settings in this order: system prompt, metadata merge, then LLM config. Each step is skipped if the corresponding field in the definition is empty or null.

​
DefinitionLoopFactory

Creates a fully configured AgentLoop from a definition. This factory implements CanInstantiateAgentLoop and is used internally by SendMessage and other session actions. 
use Cognesy\Agents\Capability\AgentCapabilityRegistry;
use Cognesy\Agents\Capability\Bash\UseBash;
use Cognesy\Agents\Template\Factory\DefinitionLoopFactory;

$capabilities = new AgentCapabilityRegistry();
$capabilities->register('use_bash', new UseBash());

$factory = new DefinitionLoopFactory($capabilities);
$loop = $factory->instantiateAgentLoop($definition);
// @doctest id="34c6"
The factory builds the loop by applying the definition’s fields in order:
  1. LLM config — if the definition specifies an llmConfig, a ToolCallingDriver is created with that config.
  2. Guards — if the definition declares a non-empty budget, UseGuards is applied with the budget’s limits.
  3. Capabilities — each named capability in the definition is resolved from the AgentCapabilityRegistry and applied to the builder.
  4. Tools — if the definition references named tools, they are resolved from the tool registry and added via UseTools.

​
Providing a Tool Registry

When the definition references tools by name (via tools or toolsDeny), you must provide a tool registry that implements CanManageTools: 
use Cognesy\Agents\Tool\ToolRegistry;

$tools = new ToolRegistry();
$tools->register($searchTool);
$tools->register($readFileTool);

$factory = new DefinitionLoopFactory(
    capabilities: $capabilities,
    tools: $tools,
);
// @doctest id="66bf"
If a definition references tools and no registry is provided, DefinitionLoopFactory throws an InvalidArgumentException. Unknown tool names also cause an exception, listing which tools could not be found.

​
Event Propagation

Pass an event handler to propagate events from instantiated loops to a parent dispatcher: 
use Cognesy\Events\Dispatchers\EventDispatcher;

$events = new EventDispatcher('session');
$factory = new DefinitionLoopFactory($capabilities, $tools, $events);
// @doctest id="6d7f"

​
AgentCapabilityRegistry

The AgentCapabilityRegistry maps string names to capability instances. It is the bridge between definition files (which reference capabilities by name) and the PHP capability classes that implement them. 
use Cognesy\Agents\Capability\AgentCapabilityRegistry;
use Cognesy\Agents\Capability\Bash\UseBash;
use Cognesy\Agents\Capability\File\UseFileTools;

$capabilities = new AgentCapabilityRegistry();

// Register a pre-built instance
$capabilities->register('use_bash', new UseBash());

// Register a factory for lazy instantiation
$capabilities->registerFactory('use_file_tools', fn() => new UseFileTools('/my/project'));

// Query the registry
$capabilities->has('use_bash');     // true
$capabilities->get('use_bash');     // returns the UseBash instance
$capabilities->names();             // ['use_bash', 'use_file_tools']
$capabilities->count();             // 2
// @doctest id="d9f1"
Factory-registered capabilities are instantiated on first access and cached for subsequent lookups. If the factory does not return a CanProvideAgentCapability, an InvalidArgumentException is thrown.

​
Using with Subagents

The AgentDefinitionRegistry implements CanManageAgentDefinitions, making it the standard provider for the UseSubagents capability. When a parent agent calls spawn_subagent, the subagent system looks up the named definition in this registry and builds a child loop from it. 
use Cognesy\Agents\Builder\AgentBuilder;
use Cognesy\Agents\Capability\Subagent\UseSubagents;
use Cognesy\Agents\Template\AgentDefinitionRegistry;

$registry = new AgentDefinitionRegistry();
$registry->loadFromDirectory('/agents');

$agent = AgentBuilder::base()
    ->withCapability(new UseSubagents(provider: $registry))
    ->build();
// @doctest id="9201"
The subagent tool’s schema automatically includes the list of available agents and their descriptions, so the LLM knows which subagents it can delegate to. See Subagents for the full delegation model.

​
Serialization

AgentDefinition supports round-trip serialization via toArray() and fromArray(): 
$array = $definition->toArray();
$restored = AgentDefinition::fromArray($array);
// @doctest id="e85a"
This is used internally by the session persistence layer to store agent definitions alongside session state. The fromArray() method also accepts title as an alias for label to support legacy formats.