---
title: "A2A server"
manual: "LLM Foundation"
version: "0.50"
permalink: "https://docs.typo3.org/permalink/netresearch/nr-llm:administration-a2a-server@0.50"
source: "Administration/A2aServer.rst"
rendered: "2026-11-17T20:50:44+00:00"
---

# A2A server {#administration-a2a-server}

nr-llm can answer other agents that speak the [Agent2Agent protocol](https://a2a-protocol.org/v1.0.1/specification/) (A2A) 1.0 over JSON-RPC.
It publishes selected LLM configurations as skills, and a registered remote
client sends a message to one of them. The message becomes an agent run that a
worker executes; the client receives the result as an A2A task
([ADR-280](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-280@0.50), [ADR-282](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-282@0.50), [ADR-283](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-283@0.50)).

This page covers stages 3 to 5b of spec 051 (tasks, a client that answers a
task waiting for input, streams, and push notifications to a client's
webhook) and the files of stage 5c, switched off by default: files a client
sends, files from FAL a task sends, inline or as a protected download, and
a client's file taken into the profile's FAL inbox after a person approved
it ([Taking a client's file into FAL](https://docs.typo3.org/permalink/netresearch/nr-llm:administration-a2a-server-fal-adoption@0.50)).

## Switch it on {#switch-it-on}

1.  Set **Answer A2A requests (server role)**
    (`a2a.server.enabled`) in the extension configuration. Off, no site
    answers an A2A request, whatever its settings say.
1.  Name the base URL in the settings of each site that should answer, for
    example in `config/sites/<site>/settings.yaml`:

    ```yaml
    nrllm:
      a2a:
        baseUrl: 'https://www.example.org/a2a'
    ```

    Write the nested form shown here, or add the set
    **LLM Foundation** (`netresearch/nr-llm`) to the site's
    dependencies. On a site without the set, a dotted key such as
    `nrllm.a2a.baseUrl: '…'` is not read, and the site answers no A2A
    request ([Setting it up](https://docs.typo3.org/permalink/netresearch/nr-llm:administration-site-settings-setup@0.50)).

    The JSON-RPC endpoint is this URL; the agent card is published at
    `https://www.example.org/a2a/.well-known/agent-card.json`. A site
    without the setting answers neither. Every URL in the card and in a
    response is built from this setting, never from the request's `Host`
    header; a request to another host, scheme or port is not an A2A request
    and passes on to the site.
1.  Run a worker. A task is accepted only while a worker can be shown to run:
    a `messenger:consume` consumer with a heartbeat, or a tick of
    `nrllm:agent:work` within the last 120 seconds. Schedule
    `nrllm:agent:work` every minute on an installation without a consumer.
    `nrllm:agent:status --transport=sweep --minimum-workers=1` checks the
    sweep. Without a worker, `SendMessage` answers HTTP 503 with
    `WORKER_UNAVAILABLE` and stores nothing.

## Publish a skill {#publish-a-skill}

Create an **A2A Publication Profile** record (administrators only).

-   **Skill id, name, description, tags, examples**

    What the agent card lists for the skill. The skill id is how a client
    names it.

-   **Domain handler**

    What turns the client's message into the run and the run's answer into
    the result. `nr_llm.text` sends the message text to the LLM
    configuration and returns the answer as one text artifact: a text check or
    a summary, with the instructions of the configuration's system prompt.
    `nr_llm.page_metadata.v1` writes the metadata of one page in one
    language as a draft, held to that page and language
    ([A2A skill: page metadata](https://docs.typo3.org/permalink/netresearch/nr-llm:a2a-page-metadata-skill@0.50)).

    Two handlers are for editorial texts used outside TYPO3
    ([ADR-302](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-302@0.50)). Their final answer is checked against the term
    lists and the rule-set judge of the configuration before it is delivered,
    whatever its length and also when the run only read. A broken term, a rule
    broken under a judge in block mode, a judge in block mode that cannot
    answer, or term lists that cannot be read stop the task as failed. A judge
    in report mode that cannot answer, and a configuration with no term list
    and no judge, deliver the text as not checked.

    -   `nr_llm.editorial_text` writes the text from the client's message, with
        the read-only tools the profile allows. Writing tools and tools that ask
        the client a question, such as `ask_choice`, are not offered: a
        question would reach the client before the check.
    -   `nr_llm.editorial_check` checks the text the client sends, for example
        a draft the editor changed, without generating one: no model writes and
        no tool is called; only the judge of the configuration is asked.

    Their result has two artifacts ([ADR-301](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-301@0.50)): the first holds
    only the text, as one text part, to be pasted as it is; the second,
    `report`, holds one data part with the check, the digests of the checked
    and of the delivered text, the rule state, and an editorial state
    (`draft`, `needs_revision`, `needs_human_review`). A completed task is
    no approval to publish; the editorial state says what the text still needs.
    A text checked by `nr_llm.editorial_check` is a `draft` only at the
    answer level `full`, because below it the check reads the redacted text.
    A stopped task carries only the report, and only where its answer level is
    `full` or `redacted`; below that it carries none. A level tightened
    after the result was stored withholds the report's findings.

-   **LLM configuration**

    The configuration the runs use. If its answer level keeps no result
    (`metadata` or `none`, set on its provider), the profile cannot be
    public, and a call is refused before a task exists with
    `RESULT_NOT_RETAINABLE` ([ADR-282](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-282@0.50)). A configuration that
    is switched off, or restricted to backend groups the client's technical
    user is not in, refuses a call with `PROFILE_UNAVAILABLE`. The agent card
    lists a skill only while its handler is available and its configuration
    is switched on and keeps a result.

-   **Tools**

    Comma-separated tool names the run may use. Without **May write**,
    a profile offers only tools that declare that they only read: a list with
    any other tool is not stored, and an existing list stays as it was. Empty:
    no tools. A run can ask the client a question with
    `ask_choice` when the tool is listed here and enabled in the tool
    management; the task then waits for the client's answer (see below).

-   **May write**

    The run may use the profile's writing tools too. They write drafts only,
    into the pinned workspace of the calling client ([ADR-260](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-260@0.50));
    a writer that does not support workspaces refuses there. A client pinned
    to live cannot call a writing skill: the record is not saved that way, and
    a call is refused with `-32004`. A write that needs an approval waits for
    a person of this installation, as in every run; the task stays
    `WORKING` meanwhile, with the status message \``The task is waiting for
    an approval in TYPO3.``. The result of a writing task carries a second
    artifact, ``writes``, that lists every write the run executed (table,
    record uid, workspace, kind), taken from the write events, not from the
    model's answer; a run that wrote nothing says so.
    The one exception to "drafts only" is ``adopt_client_file``, which
    stores a client's file in the skill's inbox folder as a new FAL file. A
    FAL file has no draft; nothing uses it until an editor references it in
    a record of a workspace (see
    :ref:`Taking a client's file into FAL \<administration-a2a-server-fal-adoption>\`).

-   **Send FAL files to clients**

    The recipient approval for `send_fal_file`: the clients of this skill
    may receive files from FAL that their technical user may read (see
    [Files from FAL](https://docs.typo3.org/permalink/netresearch/nr-llm:administration-a2a-server-fal-export@0.50)). Off by
    default; off, the tool refuses every file. It is read at each call, so
    clearing it while a run is under way stops the next file.

-   **Inbox folder for client files**

    The one folder `adopt_client_file` stores a client's file in, as a
    combined identifier such as `2:/a2a-inbox/` (see
    [Taking a client's file into FAL](https://docs.typo3.org/permalink/netresearch/nr-llm:administration-a2a-server-fal-adoption@0.50)).
    The folder must not be public: a folder of a storage marked public, of a
    `Local` storage whose base path lies in the web root, or of a storage
    that does not exist is not stored. Empty, the default: no file is taken
    into FAL.

-   **Active task quota**

    How many tasks of this skill, from all clients together, may be queued or
    running at once. `0`: no limit of its own.

-   **Public**

    Listed on the card and callable. A profile that is not public cannot be
    called by any client.

-   **Input modes**

    The media types a client may send to the skill: `text/plain` and, while
    files are switched on (see [Files](https://docs.typo3.org/permalink/netresearch/nr-llm:administration-a2a-server-files@0.50)),
    `application/json`, `application/pdf`, `image/png` and
    `image/jpeg`. While files are off the card lists `text/plain` for
    every skill, whatever is ticked here.

Results are `text/plain`, and the files a skill sends from FAL. While files
are on, a skill that lists `send_fal_file` and approves its clients as
recipients lists the five file types among its output modes on the card.

## Register a client {#register-a-client}

Create an **A2A Client** record (administrators only):

-   **Technical backend user**

    Every task of the client runs as this backend user, with exactly its
    permissions. It must be enabled and must not be an administrator; the
    record cannot be enabled otherwise, and a request is refused if the user
    changed since. Prepare a user for this purpose.

-   **Workspace**

    The workspace the client's runs act in; `0` is live. A client that may
    call a writing skill needs a draft workspace.

-   **Skills it may call**

    The publication profiles the client may use. A client allowed one skill
    needs to name none; a client allowed several names the skill in each
    message, as `SendMessageRequest.metadata` member
    `https://nr-llm.netresearch.de/a2a/ext/profile/v1` with the skill id as
    value. Otherwise the call is refused with `PROFILE_REQUIRED`.

-   **Task limit**

    How many of the client's tasks may be queued or running at once.

-   **Enabled, expires**

    A disabled or expired client is refused like an unknown one.

Then issue its token:

```bash
vendor/bin/typo3 nrllm:a2a:client:token <client uid>
```

The command prints the token once. The record keeps only its public prefix
and its SHA-256; nobody can read the token from the database. Running the
command again rotates the token: the old one stops working at once, and the
client keeps its tasks, which belong to the record, not to the token. The
client sends the token as `Authorization: Bearer <token>`.

In the backend the module **AI > A2A tokens** does the same without a
shell: **Generate token** and **Rotate token** per record, and
**Revoke**. Editors can also issue tokens that act as their own
account, within limits that you set per backend group; see
[A2A tokens in the backend](https://docs.typo3.org/permalink/netresearch/nr-llm:administration-a2a-tokens@0.50).

## What a client gets {#what-a-client-gets}

-   **`SendMessage`**

    Creates a task and a queued run. The request never executes the run.
    Without `returnImmediately`, the request waits until the task is
    finished, failed, cancelled, rejected or waiting for input, at most
    `a2a.server.blockingWaitSeconds` (default 20, at most 100). After that
    it answers HTTP 504 with JSON-RPC `-32603`, reason
    `BLOCKING_DEADLINE_EXCEEDED` and the task id; the task goes on and is
    read with `GetTask`. A repeated `messageId` of the same client returns
    the task the first one created.

-   **Answering a task (`SendMessage` with `taskId`)**

    A task whose run asks a question is `INPUT_REQUIRED`; its status
    message holds the question and, where the question offers a choice, the
    answers it accepts. The client answers with a message that carries the
    task's `taskId` (and its `contextId`, or none: the task's is used).
    The text is the answer to a question with one free or chosen answer; a
    question with several values takes a JSON object. The answer is checked
    like one from the backend ([ADR-281](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-281@0.50)): it must fit the
    question, and the client's technical user must be allowed to run the
    tool that asked. It is then stored, the run is handed to the worker and
    the task is `WORKING`; nothing runs in the request. A task that does
    not wait for the client, or has ended, takes no message (`-32004`); a
    finished task is never reopened. Only the client's own task can be
    answered, in its own context and its own skill. Before the run goes on,
    and at every later resume, the client record, its technical user, its
    workspace and the skill are checked again; a client disabled or expired,
    a skill withdrawn from it or no longer public, a changed technical user or
    workspace, or a tool the run was given that the skill no longer grants
    (removed from it, or a writing tool after **May write** was
    cleared) fails the task. A repeated `messageId` returns the task.

    `AUTH_REQUIRED` is never set: no run of this installation waits for a
    credential that a client supplies out of band.

-   **`SendStreamingMessage`, `SubscribeToTask`**

    Answer with Server-Sent Events (`text/event-stream`) while
    **Answer A2A streams** (`a2a.server.streaming`, on by default)
    is on; off, the card declares no `streaming` and both are refused with
    `-32004`. `SendStreamingMessage` accepts the message like
    `SendMessage` without waiting, takes no waiting slot, and streams the
    task it created (or the message the skill answered with). Each event is one
    `data:` line holding a JSON-RPC response with the request's id. The
    first event is the task as `GetTask` returns it; after it come only
    changes that were stored later, in order: a `statusUpdate` per state,
    and an `artifactUpdate` per artifact, always whole (`lastChunk` true),
    just before the status that announces it. No part of an answer leaves
    before the run has finished and its output checks have passed: a stream
    carries status progress until then, for every skill.

    A stream closes after a terminal state or `INPUT_REQUIRED`, and after
    **Longest A2A stream** (`a2a.server.streamMaxSeconds`, default
    300); a comment line keeps it alive at least every 15 seconds. Closing a
    stream, or a client that goes away, never cancels the task. A client
    whose record is disabled, expires or loses its token while it reads is
    cut off within 10 seconds. `SubscribeToTask` on a finished task is
    `-32004`; recovery after a lost stream is `GetTask` or a new
    subscription, and `Last-Event-ID` is ignored.

-   **`GetTask`, `ListTasks`, `CancelTask`**

    Only the client's own tasks. Another client's task and a task that does
    not exist are the same `-32001`. `ListTasks` sorts by status time,
    newest first, pages with an opaque token bound to the client, its skills
    and the filter, and leaves out artifacts unless `includeArtifacts` is
    true.

-   **Task states**

    `SUBMITTED` while queued, `WORKING` while running (also while the run
    waits for an approval in the backend or for a remote agent, and after the
    client answered), `INPUT_REQUIRED` while the run waits for the client's
    answer, `COMPLETED`
    with the answer, `FAILED` with a fixed message that names no internal
    detail, `CANCELED`, and `REJECTED` when the input was refused before
    the run started. While the run waits for an approval, a `WORKING` task
    carries the status message \``The task is waiting for an approval in
    TYPO3.``; while it waits for a remote agent, ``The task is waiting for a
    remote agent.`` Neither names the approval, the agent or anything else of
    this installation, and both are gone once the run goes on
    (:ref:`ADR-310 \<adr-310>`). ``GetTask``, ``ListTasks``, the stream and push
    carry the change like any other. The result is kept at the run's answer
    level and purged with the run (:ref:`ADR-282 \<adr-282>\`).

## Push notifications {#push-notifications}

Push is off by default. Switched on with **Send A2A push notifications**
(`a2a.server.push`), the agent card declares `pushNotifications` and a
client can register webhooks for its own tasks, with
`CreateTaskPushNotificationConfig` or embedded in `SendMessage`
([ADR-285](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-285@0.50)). Another client's task is not found.

-   **Targets.** A webhook must be an https URL and pass the address guard when
    it is registered and again before every delivery: public addresses only, no
    host of this installation, and the host lists `a2a.push.allowedHosts` and
    `a2a.push.deniedHosts`, which are separate from those of the remote
    agents. Through an HTTP proxy only with `a2a.push.allowViaProxy` and an
    allowlist.
-   **Credentials.** The one supported scheme is a Bearer credential in
    `authentication`; it is sent as `Authorization: Bearer`. The optional
    `token` is stored and returned but never sent. Both are stored sealed,
    like the run state; `Get` and `List` answer the credential masked. A
    secret a client puts into the URL itself, in its query string, is not a
    credential: it is stored and shown like the rest of the URL.
-   **No update.** A `Create` with the id of an existing config of the same
    task replaces it. `Delete` is idempotent. A task has at most
    `a2a.server.maxPushConfigsPerTask` (default 4) configs, a client
    `a2a.server.maxPushConfigsPerClient` (default 100).
-   **Delivery.** Every stored change of a task writes one delivery job per
    config in the same transaction. `nrllm:a2a:poll` delivers them; schedule
    it at least every minute while push is on. No request ever calls a
    webhook. A delivery is an HTTP POST of `{"task": …}` with
    `Content-Type: application/a2a+json`: the task as it is when it is sent,
    without history, so an older job not yet sent is superseded by the newest.
    The timeout is 15 seconds.
-   **One pass, bounded.** A run of `nrllm:a2a:poll` claims no further
    delivery once 30 seconds have passed since its deliveries started, so it
    lasts at most that plus one attempt. It takes at most 10 deliveries per
    client, and the clients take turns: a client whose webhooks answer slowly
    does not hold back the deliveries of the others. What is left goes out in
    the next run.
-   **Outcomes.** 2xx acknowledges. A timeout, a broken connection, 429, 502,
    503, 504 and a redirect are retried after 5, 10, 20 … seconds, at most
    eight attempts and within a day; then the job is abandoned and logged. The
    backoff and the attempts belong to the config, not to one change: a new
    change of the task while a delivery waits to be retried waits for the same
    backoff and continues the count. A change written while an attempt is on
    its way is normally not sent before that attempt ends. When the attempt
    succeeds, that change goes out at once with all eight attempts; when the
    eighth attempt fails, it is abandoned with it, and the next change starts
    over. An attempt counts once it is started, also when the worker fails
    before it records the answer. 401 and 403 pause the config
    (`auth_failed`); 404, 410 and a refused address
    stop it (`stopped`). A paused or stopped config sends nothing more; the
    client registers a new one. Any other answer fails that one delivery.
-   **After a delete** no new attempt starts. A request already on its way may
    still arrive.
-   **Revoked clients and new tokens.** Revoking a client, or issuing it a
    new token, stops its configs: a config belongs to the token it was created
    with. Before every attempt the sender checks again that the client still
    holds that token, is enabled and not expired, and that its technical
    backend user is usable; otherwise the config stops.
-   **Switching push off** stops every delivery at once and writes no new
    jobs; the methods answer `-32003`. Jobs already written wait and go out
    if push is switched on again within a day. `nrllm:a2a:poll` still
    abandons the jobs past that day and removes finished jobs after a week
    while push is off.
-   **In the backend** the configs are records of the type
    **A2A Push Config** on the root page, read-only, with their state
    and the reason of the last refusal; the credential is not shown.

<a id="administration-a2a-server-fal-adoption"></a>
<a id="administration-a2a-server-fal-export"></a>

## Files {#administration-a2a-server-files}

Off by default. With **Accept A2A files (server role)**
(`a2a.files.enabled`) on, a client message may carry file parts besides its
text ([ADR-284](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-284@0.50)). Off, every part other than `text/plain`
text is refused with `-32005`, as before. Switched off while a task with
files waits for the worker, that task fails before its files are fetched
or read.

-   **What is accepted**

    A `raw` part (the bytes, base64 in the JSON) that names its
    `mediaType`, one of `text/plain`, `application/json`,
    `application/pdf`, `image/png` and `image/jpeg`, and that the skill
    lists among its **Input modes**. Each file is checked against its
    type before anything is stored: text must be UTF-8 without control
    characters and must not open with HTML, SVG or XML markup; JSON must parse;
    a PDF needs its header and cross-reference trailer, must not be encrypted
    and must not name JavaScript, launch actions, embedded files, rich media
    or XFA forms; an image must carry its type's signature, be at most 4096 x
    4096 pixels and decode with GD (without the GD extension no image is
    accepted). The images of one message may hold at most 16,777,216 pixels
    together, read from their headers before any is decoded (`-32602`).
    The content is checked only after the skill, its input modes and the
    client's limits allow the message. Archives, HTML, SVG and any other
    type, a part without a `mediaType` and a `data` part are refused with
    `-32005`. A message that answers a waiting task carries text only.

-   **File URLs**

    A `url` part with the same `mediaType` rules is accepted only from a
    host listed in **Hosts A2A file URLs may come from**
    (`a2a.files.allowedHosts`). Unlike the host list of the A2A client, an
    empty list admits no file URL at all (`-32005`). The URL must be https
    and passes the address guard of [ADR-202](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-202@0.50) when the task is
    accepted (`-32602` otherwise): no private, loopback, link-local or
    metadata address, no credentials in the URL, no host of this
    installation, and **Hosts A2A file URLs never come from**
    (`a2a.files.deniedHosts`) is checked first. Nothing is fetched in the
    request. The worker fetches the file before the run starts, through the
    same guard again, pinned to the checked addresses, with a plain `GET`
    that carries no credential of the client or of a remote agent and no
    cookie, following no redirect and reading at most the size limit. The
    fetched bytes pass the same type check and count against the message's
    limit together with its raw files; a fetched image counts against the
    message's pixel budget together with its other images, before it is
    decoded. A refusal (a redirect, a status that
    is not 2xx, the size, the content, the guard) is stored with the file
    and fails the task; a timeout, 408, 429 or 5xx leaves the file pending
    and the run is retried like any transient failure. Once stored, the copy
    is the input: the URL is never fetched again.

-   **Sizes**

    **Largest A2A file** (`a2a.maxRawPartBytes`, default 5 MiB, at
    most 8 MiB) bounds the decoded bytes of one file and of all files of one
    message together. Sealed, a file takes about 1.8 times its size in its
    database row, which must fit into one packet of the database
    (`max_allowed_packet`, 16 MiB by default on MariaDB). The base64 text
    is measured before it is decoded. Larger is `-32602`. While files are
    on, the largest request (`a2a.server.maxRequestBytes`) grows by the
    base64 size of this limit.

-   **Where a file goes**

    Into a private store (`tx_nrllm_a2a_file`), not into FAL and not under
    any public path: one row per file with the client, the task, the origin,
    the real size, the checked type, the SHA-256, the check and approval
    state and an expiry, the bytes sealed in the row like a task's history.
    The task's history keeps a reference in place of the bytes (the part's
    `raw` is empty, its `metadata` under
    `https://nr-llm.netresearch.de/a2a/ext/file/v1` names the file id,
    SHA-256 and size). A `url` part keeps its URL in the history; in the
    store the URL is sealed like the bytes.

-   **What the run sees**

    Before the worker asks the model for the first time it checks the task's
    files against the list recorded when the task was accepted: each must be
    there, of the client, checked, approved, unexpired and unchanged.
    Otherwise the task fails and the model is never asked. The run then
    receives, after the client's text, one message per file, marked as data
    the client sent and not as instructions: text and JSON as text, an image
    as an image for a model that declares vision, and a PDF as a line naming
    it, because a run cannot read a PDF. A large text file goes into the
    prompt whole; set the size limit with the model's context in mind.

-   **Files a task sends**

    A file a task sends is one of the five types and passed the same check,
    and is stored in the same private store, with the direction `out`.
    When the run completes, each file becomes an artifact of its own. Files
    go inline as `raw` while they fit together into
    **Largest inline A2A artifact** (`a2a.maxInlineArtifactBytes`,
    default 256 KiB, at most 512 KiB, so that they still fit into one event
    of a stream at the default frame size); every further file goes out as a
    `url` to `<endpoint>/files/<file id>`, below the A2A endpoint the task
    was accepted at, as the site configures it. No artifact names a URL of
    the installation's own storage. The part's `metadata` names the file
    id, SHA-256 and size as for an inbound file. A run kept at the
    `redacted` level sends no file, because a file cannot be redacted; one
    text artifact says how many files were withheld. The files of FAL are
    the one source of such files (next section).

-   **Files from FAL**

    A run puts a file from FAL into its task's result with the tool
    `send_fal_file` (group `files`), naming the file's `sys_file` uid.
    It ships disabled. A skill offers it when all three hold: the tool is
    switched on in the tool management, the skill lists it under
    **Tools**, and **Send FAL files to clients** is on. The
    tool changes no record, so a skill without **May write** can
    offer it.

    At each call the tool checks, in this order: the run is a task of the
    server role; files are on; the skill approves its clients as recipients;
    the task keeps its answer at the `full` level (below it no file is
    sent, so the tool refuses rather than claim a delivery). Then the file: the client's technical user must reach it through its
    file mounts and file permissions, read for this run
    (`FalStorageGate::isFileAccessible()`). A file outside those mounts,
    a uid that no file carries and a run without a user get the same answer,
    `Asset not found or not permitted.`, so a run cannot find out which
    files exist. A file the user may read is sent only when it is at most
    **Largest A2A file** large, is of one of the five types (by the
    type FAL recorded for it) and passes that type's check. The model reads
    the file's name, type, size and id, never its content. A second call for
    the same file adds nothing; a retried run does not send a file twice.
    The file goes out as described above: inline or as a download, never as a
    URL of the installation's own storage.

    The file mounts and file permissions are read anew for every execution
    of a run, also by a long-running worker (`messenger:consume`): a mount
    taken away from the technical user stops the next run from sending a
    file in it. Which storages a user reaches at all comes from TYPO3, which
    keeps the mount records it read for the life of the worker process: per
    user and workspace in TYPO3 14.3.11, one entry for all users in 13.4.30
    and 14.3.0. Each file is still checked against the mounts read for the
    run. Restart the worker after giving a technical user its first mount in
    a storage.

-   **Taking a client's file into FAL**

    A run stores a file the client sent with the task in FAL with the tool
    `adopt_client_file` (group `files`), naming the file by its number,
    the N of the line "File N of M from the client" the run received
    ([ADR-305](https://docs.typo3.org/permalink/netresearch/nr-llm:adr-305@0.50)). It ships disabled. A skill offers it when the
    tool is switched on in the tool management, the skill lists it under
    **Tools**, **May write** is on (the tool writes, so the
    calling client is pinned to a draft workspace) and
    **Inbox folder for client files** names a folder.

    -   **Where:** only into that folder. Neither the client nor the model
        chooses a folder or a storage. The folder must exist and must not be
        public: not in a storage marked public, not in a `Local` storage with
        a relative base path or with an absolute one inside the web root (as
        written or through a link), not linked into the web root itself, and not
        a processing folder (the storage's own, or one any storage assigns
        into it) or a `_recycler_` folder. Repeated slashes and `.`
        segments are dropped before the check, and the folder is stored in
        that form. Give the inbox its own
        `Local` storage with an absolute base path outside the web root. The
        tool asks this again at each call, so a storage made public later stops
        the next adoption.
    -   **Who writes:** the client's technical backend user, with its own file
        mounts and file permissions. It needs a file mount on the folder that is
        not read-only, and the permissions to read and write folders and to add
        files.
        The approving editor's rights do not count, also not an
        administrator's. The storage list the FAL tools may read from
        (storage 1 by default) does not limit the inbox.
    -   **Approval:** every call waits for the approval of a person of this
        installation, in the approvals inbox, as every writing tool does; the
        task stays `WORKING` meanwhile. A call that cannot be written is
        refused before an approval is asked: no inbox folder, a public folder,
        no such file, a file the task no longer holds, a technical user who may
        not add a file to the folder, or files switched off. The card shows the
        client's file name, the name it will be stored as, its type, size and
        the start of its SHA-256 digest, and the inbox folder, to an
        administrator and to an editor whose file mounts reach the inbox folder
        the card names; anyone else sees that the preview is withheld. If any of that
        reads differently when the approved call runs (the folder was changed,
        the name was taken, the user lost the right), the file is not stored and
        the run asks for a new approval.
    -   **Names:** the file keeps the name the client gave it, without any path
        and without Unicode format characters, with the extension of its
        checked type (`.txt`, `.json`, `.pdf`, `.png`, `.jpg`). A name
        already taken in the folder is kept: the new file gets another one
        (`report_01.txt`), and the existing file and its record stay as they
        are. The approved call writes into the folder and under the name the
        card showed and nowhere else: if two files of one name are adopted in
        one turn, or the skill's inbox folder changes after the approval, the
        call writes nothing and the file has to be adopted again with a new
        card. Two approved adoptions of the same name, carried out by two
        workers at the same instant, are not guarded against: core's Local
        driver could then replace the first file. If TYPO3 fails after it wrote the file, the answer says that a file
        of that name may remain in the inbox; it is not deleted.
    -   **Effect:** nothing references the stored file. It takes effect only
        when an editor uses it in a record of a workspace, which is published
        like any other change. The `writes` artifact of the task names the new
        `sys_file` record in workspace 0: a FAL file has no draft.
    -   **When:** a task's files are held until the task ends or the file
        expires (**Hours an A2A file is kept**), whichever comes first. An
        approval given later stores nothing, and the tool says that the file is
        no longer held.

    The cleanup of expired A2A files never deletes a file taken into FAL.

-   **Downloading a file**

    `GET <endpoint>/files/<file id>` with the client's bearer token returns
    the bytes with their type, `Content-Disposition: attachment`,
    `X-Content-Type-Options: nosniff` and `Cache-Control: no-store`. A
    file of another client, an unknown file, an expired one and one the
    task's artifacts no longer name all answer the same `404`; a file is
    served only while the artifacts, read at the run's current answer level,
    still carry it, so a tightened privacy level withdraws the download too.
    `POST <endpoint>/files/<file id>/capability` with the bearer token
    returns `{"url": ..., "expiresAt": ...}`: a URL that reads this one
    file of this one client without the bearer token for 15 minutes.

    > [!WARNING]
    > A capability URL is a transferable bearer right: whoever holds it
    > reads the file until it expires, without any other credential. It
    > stops working when it expires, when the client gets a new token and
    > when the client is disabled. Hand it on only where the file may go.
    > The capability sits in the query string, so it can end up in the
    > access log of a proxy or web server in front of the endpoint; keep
    > those logs as you would keep the file.

    A wrong, expired or revoked capability answers `401` and is logged and
    counted per source address together with failed bearer tokens, under the
    same limit (`nrllm-a2a-auth`, 10 failures per 15 minutes); over it the
    answer is `429`.

    Asking for a capability again issues a new URL and changes nothing of
    the task: its status, the artifact ids, the digest and the content stay
    as they are, and no event is written. With
    **Accept A2A files (server role)** off, the download paths are
    not answered.

-   **Cleanup**

    When a task ends (completed, failed, canceled or refused), its input
    files keep their record (id, size, SHA-256, check and approval state)
    but lose their bytes and URL in the same transaction, whatever the
    answer level: nothing reads them after a final state. A `url` part
    not fetched yet is refused (`task ended`), so a fetch still running
    stores nothing. The files a task
    sends stay until they expire, because they are its result. A task's
    files go with the run purge, like its history.
    `nrllm:privacy:purge` also deletes every file older than
    **Hours an A2A file is kept** (`a2a.files.retentionHours`,
    default 168); a queued task whose file is gone fails rather than running
    without it. Cleanup deletes rows of the store only: a file sent from FAL
    is a copy in the store, and the FAL file itself stays.

## Limits and protection {#limits-and-protection}

-   **Proxy timeouts.** A waiting request holds a PHP-FPM worker. Keep
    `a2a.server.blockingWaitSeconds` below the read timeout of every proxy in
    front of PHP-FPM; a proxy that cuts the request earlier leaves the client
    with a transport error and the task unchanged.
-   **Waiting requests.** At most `a2a.server.maxWaitingRequests` (default 4)
    blocking requests wait at the same time on the installation; one more is
    refused with HTTP 503, `WAITING_CAPACITY_EXHAUSTED`. A request with
    `returnImmediately` takes no waiting slot.
-   **Streams.** A stream holds a PHP-FPM worker while it is open. At most
    `a2a.server.maxStreamsPerTask` (default 2) streams read one task,
    `a2a.server.maxStreamsPerClient` (default 4) belong to one client, and
    `a2a.server.maxStreams` (default 8) are open on the installation; one
    more is refused with HTTP 503, `STREAM_CAPACITY_EXHAUSTED` and
    `Retry-After`, before anything is stored. A stream that dies without
    closing frees its slot within 30 seconds. An event larger than
    `a2a.server.maxFrameBytes` (default 1 MiB) is not sent; the stream ends
    and the client reads the task with `GetTask`. The first event always
    names the task: a task too large for one frame is sent without its history
    and artifacts. An answer to a waiting task sent as a stream counts against
    that task's streams before it is taken in, so a refused answer is not
    stored either.
-   **Proxies in front of a stream.** The response carries
    `X-Accel-Buffering: no` and `Cache-Control: no-cache`, and pads each
    write to 4 KiB with a comment line, so a proxy that holds small chunks
    passes every event on when it is written; nginx in front of PHP-FPM with
    its FastCGI buffering on is tested this way in CI. Apache is not. A proxy
    whose read timeout is
    below 15 seconds cuts a quiet stream; one that buffers whole responses
    regardless of these headers delivers the events only when the stream
    closes. Check the proxy chain of the installation with a
    `SubscribeToTask` before relying on streams.
-   **Request size.** A body above `a2a.server.maxRequestBytes` (default
    1 MiB, plus the base64 size of `a2a.maxRawPartBytes` while files are on)
    is refused with HTTP 413 before it is parsed; a message has at most
    16 parts. A task's history keeps the most recent 100 messages.
-   **Failed logins.** A failed authentication is logged with the source
    address, never with the token, and counted per address: after 10 failures
    in 15 minutes a failed request from that address gets HTTP 429 until the
    window passes. A request with a valid token is not limited. The rate
    limiter is `nrllm-a2a-auth`; override it like TYPO3's own limiters in
    `$GLOBALS['TYPO3_CONF_VARS']['SYS']['rateLimiter']['nrllm-a2a-auth']`.
    Behind a reverse proxy, name it in
    `$GLOBALS['TYPO3_CONF_VARS']['SYS']['reverseProxyIP']`; otherwise every
    client counts as the proxy's address and shares one limit.
-   **Refusals** name their reason (`error.data` holds a
    `google.rpc.ErrorInfo`) and, where a retry may help, a `Retry-After`
    header.
