---
title: "AI Agent"
manual: "AI Foundation"
version: "2.0"
permalink: "https://docs.typo3.org/permalink/nitsan/ns-t3af:ai-agent@2.0"
source: "Agent/Index.rst"
rendered: "2026-10-09T13:46:48+00:00"
---

# AI Agent {#ai-agent}

## Purpose {#purpose}

The **AI Agent** is a docked right-edge assistant in the TYPO3 backend. Editors ask
in plain language, review proposed changes as cards, and apply them only when they
confirm. Reads run automatically; writes never go live without approval.

**Path (settings):** **AI Foundation > AI Agent**

**Open the panel:** toolbar **Ask AI Agent**, or **Ctrl/Cmd+Shift+K**
(optional **Ctrl/Cmd+K** in the agent preferences stored in the browser).

## Prerequisites {#prerequisites}

-   TYPO3 **13.4** or **^14.3**, PHP **8.2+**
-   A tool-calling [AI provider](https://docs.typo3.org/permalink/nitsan/ns-t3af:ai-providers@2.0) marked Default, **or**
    [T3Planet Credits](https://docs.typo3.org/permalink/nitsan/ns-t3af:t3planet-credit-system@2.0) mode
-   Backend user must be allowed to use the AI Agent (see [AI Permissions](https://docs.typo3.org/permalink/nitsan/ns-t3af:ai-permissions@2.0))

## How to use it {#how-to-use-it}

1.  Open a backend module (Page, List, Filelist, …). The agent uses that module and
    page (or folder) as context.
1.  Open the panel with **Ask AI Agent** or the keyboard shortcut.
1.  Ask in the editor's backend language, or use:

    -   `/tool_name` — run a known tool by name
    -   `@table:uid` — attach a record to the request
    -   starter chips — common tasks for the current module
1.  Read tools answer in plain words. Write tools show a **preview card** first.
1.  Review the card (fields, target workspace), then **Execute** or
    **Decline**. Applied changes can be undone from the card when the
    agent offers Undo. A stale card is not written over newer edits.

## Conversations {#conversations}

Conversations are stored on the server for each backend user. Opening the agent
resumes the last-viewed conversation for the configured scope (page, module, or
user). Use the conversations list in the panel header to switch, rename, or remove
conversations. The AI provider is fixed for a conversation after the first answer.

## Workspace {#workspace}

Confirmed changes follow the workspace selected under
**AI Foundation > MCP Server** (same preference as the MCP server).
**Live** is allowed unless the editor's group has workspace enforcement that
blocks it. The panel shows which workspace a change will go to before you apply.

## Permissions and logs {#permissions-and-logs}

The agent only offers tools and fields the editor may use: page tree, tables,
fields, files, and workspaces follow the editor's own backend rights and
[AI Permissions](https://docs.typo3.org/permalink/nitsan/ns-t3af:ai-permissions@2.0). A refusal explains why in plain words.
Every refused, hidden, or failed request is written to
[AI Usage & Logs](https://docs.typo3.org/permalink/nitsan/ns-t3af:ai-usage-and-logs@2.0).

## Credits {#credits}

In T3Planet Credits mode, the agent calls the chat completions endpoint and
shows remaining credits in the panel. Exhausted credits lock the composer until
you top up. See [T3Planet Credits](https://docs.typo3.org/permalink/nitsan/ns-t3af:t3planet-credit-system@2.0).

## Settings administrators usually change {#settings-administrators-usually-change}

Configure these under **AI Foundation > AI Agent**:

-   `agentConversationScope` — which conversation opens automatically
    (`page` / `module` / `user`)
-   `agentSessionListEnabled` — show the conversations list
-   `agentSessionListDefaultFilter` — initial list filter
-   `agentMaxSessionsPerScope` / `agentMaxSessionsPerUser` — retention caps
    (`0` = unlimited)
-   `agentConversationRetentionDays` — inactive conversations → trash
-   `agentHistoryTokenBudget` — how much earlier chat is replayed to the model
-   `agentContinueAfterConfirm` — continue a multi-step plan after Execute / Decline
-   `agentMaxReadToolsPerTurn` / `agentMaxWriteDraftsPerTurn` — per-turn budgets

Cleanup of trashed conversations and related turn rows:
`t3af:agent:conversations:cleanup`.

## Limits {#limits}

-   Batch MCP tools `records_apply` and `records_undo` are **not** offered in
    the AI Agent (one-record approval cards). External MCP clients still use them;
    see [Batch writes](https://docs.typo3.org/permalink/nitsan/ns-t3af:mcp-tools-batch-writes@2.0).
-   New content elements get a default column when the plan omits one, so layout
    constraints (for example content_defender) can resolve the column on save.

## Related {#related}

-   [MCP Server](https://docs.typo3.org/permalink/nitsan/ns-t3af:mcp-server@2.0) — workspace selection and external clients
-   [MCP Tools](https://docs.typo3.org/permalink/nitsan/ns-t3af:mcp-tools@2.0) — tool catalogue shared with the agent
-   [AI Permissions](https://docs.typo3.org/permalink/nitsan/ns-t3af:ai-permissions@2.0) — group policy for the agent
-   [Release notes 2.0.0](https://docs.typo3.org/permalink/nitsan/ns-t3af:release-notes-2-0-0@2.0) — when the agent was introduced