README

Integrates an AI agent directly into TYPO3 by calling the MCP ToolRegistry natively from PHP and talking to an OpenAI-compatible LLM API. Editors work with the agent through a dedicated backend chat module; a CLI command additionally processes pending task records for scheduled/batch runs.

Installation

composer require hn/typo3-agent

Then activate the extension in TYPO3 backend or via CLI:

bin/typo3 extension:activate agent

For non-composer TYPO3 installations the TER package bundles the required PHP libraries (PhpOffice, smalot/pdfparser); a fallback autoloader in ext_localconf.php loads them when no composer autoloader has already provided them.

Configuration

Go to Settings > Extension Configuration > agent and configure:

Setting	Default	Description
`apiUrl`	`https://openrouter.ai/api/v1/`	OpenAI-compatible API base URL
`apiKey`	(empty)	API key for authentication
`model`	`anthropic/claude-haiku-4.5`	Model identifier (dropdown: Claude Opus 4.8 / Claude Haiku 4.5)
`systemPrompt`	(built-in)	System prompt for the agent
`maxIterations`	`20`	Safety limit for the agent loop
`reasoningEffort`	`medium`	Extended-reasoning strength (`off`, `low`, `medium`, `high`)

Provider Examples

The model field ships as a curated dropdown. To use another provider or model ID, adjust ext_conf_template.txt (or ship a site-specific override).

OpenRouter (default — access to many models):

apiUrl: https://openrouter.ai/api/v1/
model: anthropic/claude-haiku-4.5

OpenAI:

apiUrl: https://api.openai.com/v1/
model: gpt-5.2

Any OpenAI-compatible API:

apiUrl: https://your-provider.com/v1/
model: your-model-id

Usage

Backend Chat Module

The primary UX is the Web > TYPO3 Agent Tasks backend module. It offers:

An overview of the agent instructions that shape the assistant's behavior (see the Agent Instructions section below).
An overview of chats scoped to the current page,
An overview of chats on any subpage
An individual chat view that shows the full conversation together with the associated workspace changes — the records the agent touched in the current workspace.

Attachments & Multimodal

Files can be dragged onto the composer or picked via the file browser. The chat UI pre-flights each attachment against an allowlist and size cap so users see up-front whether a file will be embedded as content for the LLM or only referenced by metadata.

Kind	Formats	Size cap
Image	PNG, JPEG, WebP, GIF	5 MB
PDF	PDF	50 MB
Spreadsheet	XLSX, ODS, XLS, CSV	25 MB
Document	DOCX, ODT, RTF, TXT, Markdown, HTML	25 MB
Presentation	PPTX, ODP	25 MB

Attachments enter the conversation as multimodal tool messages via the MCP tools listed under Architecture below (image bytes for ViewImageTool, extracted text/pages for the PDF and Office tools).

Creating Tasks Directly (List Module / CLI)

For scheduled or automated runs — batch seeding, cron-driven workflows, external triggers — you can also create task records directly:

Open the List module in TYPO3 backend
Navigate to the page you want the agent to work on
Create a new Agent Task record
Fill in the Title and Prompt fields
Save the record (status defaults to "Pending")

The task's pid (page ID) provides context — the agent automatically loads information about that page. The task's cruser_id determines which backend user's permissions the agent uses for tool execution.

Note: TYPO3 13.4 no longer auto-populates cruser_id via DataHandler. When cruser_id is 0 (default), the agent falls back to admin context. To run the agent as a specific user, set cruser_id manually on the task record.

Agent Instructions

Editors can maintain reusable instructions for the agent — tone of voice, wording rules, or how to handle specific content elements or records — as Agent Instruction records (tx_agent_instruction). This follows the progressive-disclosure idea of the SKILL.md open standard: the agent is its own harness, so the extension implements the pattern itself (provider-neutral — the OpenAI-compatible chat API has no native skills parameter).

Each instruction has a mode:

Always — the body is appended to the agent's system prompt for every new chat (global base rules). Use sparingly for guidance that always applies.
On demand — only the name and the "when to use" hint go into the prompt as a short index; the agent loads the full body via the GetInstruction tool when it is about to produce the relevant kind of content. This keeps the prompt small and scales to many instructions.

Note: Instructions are baked into the conversation at creation time, so they apply to newly started chats — chats already in progress keep the prompt they were created with.

Each record has:

Field	Description
Name	Short label, shown in the prompt index and the read-only panel
Mode	`Always` (in every prompt) or `On demand` (loaded via `GetInstruction`)
When to use	Short hint shown in the prompt index so the agent knows when an on-demand instruction applies
Instruction content	The guidance itself — authored as rich text; converted to plain text/Markdown before it reaches the LLM
Hidden / Start / Stop	Standard visibility controls to stage or retire instructions without deleting them

Where to keep them: create a dedicated folder (SysFolder) and store the instruction records there.

Restricting who may edit (native TYPO3 permissions): the extension does not hard-code a group. Instead, grant editing to the desired backend group via the standard access mechanism:

Edit the backend group in Backend Users > Groups.
Under Access Lists > Tables (modify), enable Agent Instruction.
Give the group access to the SysFolder that holds the records (DB mounts / page permissions).

Groups without modify rights can still read the instructions, so they remain visible in the List module and in the chat info panel.

Viewing: the instructions appear in a collapsible panel at the top of the AI chat (both the chat list and individual chats), and — like any record — in the List module.

Running the Agent from the CLI

Process all pending tasks:

bin/typo3 agent:run

Process a specific task by UID:

bin/typo3 agent:run --task=42

Limit the number of tasks processed:

bin/typo3 agent:run --limit=5

Task Lifecycle

State transitions run through Classes/Domain/TaskStateMachine.php.

Status	Value	Description
Pending	0	Ready to be picked up by `agent:run`
In Progress	1	Currently being processed
Ended	2	Agent finished, result available
Failed	3	Error occurred, messages preserved
Cancelled	4	Run was canceled before completion

Resuming Failed Tasks

When a task fails, its conversation state (messages) is preserved. To resume:

Fix the underlying issue (API key, network, etc.)
Set the task status back to "Pending" in the backend
Run agent:run again — it resumes from the last saved messages

Or resume directly: bin/typo3 agent:run --task=42

Scheduler

The agent:run command is schedulable — you can set it up as a recurring task in the TYPO3 Scheduler to automatically process pending tasks.

Workspaces

Agent tasks are workspace-aware: each task record stores a workspace_id (set automatically) and the agent runs against that workspace's data. Two event listeners hook into the workspace lifecycle: one clears change tracking on publish, the other filters the workspace diff view to the records the task actually touched. In the chat UI, the workspace-changes drawer surfaces those tracked records inline.

Architecture

The extension uses the ToolRegistry from hn/typo3-mcp-server to access the core TYPO3 tools (GetPage, GetPageTree, Search, ReadTable, WriteTable, …) natively from PHP without MCP protocol overhead.

On top of that it registers its own MCP tools under Classes/MCP/Tool/:

GetInstructionTool — progressive disclosure of on-demand instruction bodies.
GetFileInfoTool — cheap FAL metadata lookup.
ViewImageTool, ViewPdfPageTool — image and PDF-page bytes returned as multimodal content.
ReadPdfTextTool — extracts text from PDF attachments via smalot/pdfparser.
ReadSpreadsheetTool, ReadDocumentTool, ReadPresentationTool — structured content extraction from Office and OpenDocument files via PhpOffice.

The messages JSON field in each task record stores the full OpenAI messages array — the complete conversation state. This enables resumability, the SSE streaming loop, and the chat UI's message history.

Development

Run the functional tests (SQLite via typo3/testing-framework):

composer install
composer test

The bin/typo3 agent:repro-multimodal command (see Classes/Command/ReproMultimodalCommand.php) probes which LLM providers accept multimodal tool results — useful when adding or debugging providers.

TER release builds run through composer build:ter (see Build/build-ter.sh) and a matching GitHub Actions workflow. Functional tests also run in CI across the supported PHP and TYPO3 matrix.

hn / typo3-agent

Maintainers

Package info

Statistics

Security