A2A server
nr-llm can answer other agents that speak the Agent2Agent protocol (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, ADR-282, ADR-283).
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).
Switch it on
- Set Answer A2A requests (server role)
(
a2a.) in the extension configuration. Off, no site answers an A2A request, whatever its settings say.server. enabled -
Name the base URL in the settings of each site that should answer, for example in
config/:sites/<site>/ settings. yaml nrllm: a2a: baseUrl: 'https://www.example.org/a2a'Copied!Write the nested form shown here, or add the set LLM Foundation (
netresearch/) to the site's dependencies. On a site without the set, a dotted key such asnr- llm nrllm.is not read, and the site answers no A2A request (Setting it up).a2a. base Url: '…' The JSON-RPC endpoint is this URL; the agent card is published at
https://. 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'swww. example. org/ a2a/. well- known/ agent- card. json Hostheader; a request to another host, scheme or port is not an A2A request and passes on to the site. - Run a worker. A task is accepted only while a worker can be shown to run:
a
messenger:consumer with a heartbeat, or a tick ofconsume nrllm:within the last 120 seconds. Scheduleagent: work nrllm:every minute on an installation without a consumer.agent: work nrllm:checks the sweep. Without a worker,agent: status -- transport=sweep -- minimum- workers=1 Sendanswers HTTP 503 withMessage WORKER_and stores nothing.UNAVAILABLE
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_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.llm. text nr_writes the metadata of one page in one language as a draft, held to that page and language (A2A skill: page metadata).llm. page_ metadata. v1 Two handlers are for editorial texts used outside TYPO3 (ADR-302). 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_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 asllm. editorial_ text ask_, are not offered: a question would reach the client before the check.choice nr_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.llm. editorial_ check
Their result has two artifacts (ADR-301): 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_). A completed task is no approval to publish; the editorial state says what the text still needs. A text checked byhuman_ review nr_is allm. editorial_ check draftonly at the answer levelfull, because below it the check reads the redacted text. A stopped task carries only the report, and only where its answer level isfullorredacted; 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
(
metadataornone, set on its provider), the profile cannot be public, and a call is refused before a task exists withRESULT_(ADR-282). A configuration that is switched off, or restricted to backend groups the client's technical user is not in, refuses a call withNOT_ RETAINABLE PROFILE_. The agent card lists a skill only while its handler is available and its configuration is switched on and keeps a result.UNAVAILABLE - 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_when the tool is listed here and enabled in the tool management; the task then waits for the client's answer (see below).choice - 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);
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 staysWORKINGmeanwhile, 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 executedTaking a client's file into FAL <administration-a2a-server-fal-adoption>`).(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: - Send FAL files to clients
- The recipient approval for
send_: the clients of this skill may receive files from FAL that their technical user may read (see Files from FAL). 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.fal_ file - Inbox folder for client files
- The one folder
adopt_stores a client's file in, as a combined identifier such asclient_ file 2:/(see Taking a client's file into FAL). The folder must not be public: a folder of a storage marked public, of aa2a- inbox/ Localstorage 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/and, while files are switched on (see Files),plain application/,json application/,pdf image/andpng image/. While files are off the card listsjpeg text/for every skill, whatever is ticked here.plain
Results are text/, and the files a skill sends from FAL. While files
are on, a skill that lists send_ and approves its clients as
recipients lists the five file types among its output modes on the card.
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;
0is 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
SendmemberMessage Request. metadata https://with the skill id as value. Otherwise the call is refused withnr- llm. netresearch. de/ a2a/ ext/ profile/ v1 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:
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.
What a client gets
SendMessage - Creates a task and a queued run. The request never executes the run.
Without
return, the request waits until the task is finished, failed, cancelled, rejected or waiting for input, at mostImmediately a2a.(default 20, at most 100). After that it answers HTTP 504 with JSON-RPCserver. blocking Wait Seconds -32603, reasonBLOCKING_and the task id; the task goes on and is read withDEADLINE_ EXCEEDED Get. A repeatedTask messageof the same client returns the task the first one created.Id - Answering a task (
SendwithMessage task)Id -
A task whose run asks a question is
INPUT_; 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'sREQUIRED task(and itsId context, 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): 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 isId 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 repeatedmessagereturns the task.Id AUTH_is never set: no run of this installation waits for a credential that a client supplies out of band.REQUIRED Send,Streaming Message SubscribeTo Task -
Answer with Server-Sent Events (
text/) while Answer A2A streams (event- stream a2a., on by default) is on; off, the card declares noserver. streaming streamingand both are refused with-32004.Sendaccepts the message likeStreaming Message Sendwithout waiting, takes no waiting slot, and streams the task it created (or the message the skill answered with). Each event is oneMessage data:line holding a JSON-RPC response with the request's id. The first event is the task asGetreturns it; after it come only changes that were stored later, in order: aTask statusper state, and anUpdate artifactper artifact, always whole (Update lasttrue), 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.Chunk A stream closes after a terminal state or
INPUT_, and after Longest A2A stream (REQUIRED a2a., 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.server. stream Max Seconds Subscribeon a finished task isTo Task -32004; recovery after a lost stream isGetor a new subscription, andTask Last-is ignored.Event- ID Get,Task List,Tasks CancelTask - Only the client's own tasks. Another client's task and a task that does
not exist are the same
-32001.Listsorts by status time, newest first, pages with an opaque token bound to the client, its skills and the filter, and leaves out artifacts unlessTasks includeis true.Artifacts - Task states
SUBMITTEDwhile queued,WORKINGwhile running (also while the run waits for an approval in the backend or for a remote agent, and after the client answered),INPUT_while the run waits for the client's answer,REQUIRED COMPLETEDwith the answer,FAILEDwith a fixed message that names no internal detail,CANCELED, andREJECTEDwhen the input was refused before the run started. While the run waits for an approval, aWORKINGtask 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 onADR-310 <adr-310>(: ref: ). ``GetADR-282 <adr-282>`).Task``, ``List Tasks``, 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:
Push notifications
Push is off by default. Switched on with Send A2A push notifications
(a2a.), the agent card declares push and a
client can register webhooks for its own tasks, with
Create or embedded in Send
(ADR-285). 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.andpush. allowed Hosts a2a., which are separate from those of the remote agents. Through an HTTP proxy only withpush. denied Hosts a2a.and an allowlist.push. allow Via Proxy - Credentials. The one supported scheme is a Bearer credential in
authentication; it is sent asAuthorization: Bearer. The optionaltokenis stored and returned but never sent. Both are stored sealed, like the run state;GetandListanswer 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
Createwith the id of an existing config of the same task replaces it.Deleteis idempotent. A task has at mosta2a.(default 4) configs, a clientserver. max Push Configs Per Task a2a.(default 100).server. max Push Configs Per Client - Delivery. Every stored change of a task writes one delivery job per
config in the same transaction.
nrllm:delivers them; schedule it at least every minute while push is on. No request ever calls a webhook. A delivery is an HTTP POST ofa2a: poll {"task": …}withContent-: 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.Type: application/ a2a+json - One pass, bounded. A run of
nrllm: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.a2a: poll - 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_); 404, 410 and a refused address stop it (failed 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:still abandons the jobs past that day and removes finished jobs after a week while push is off.a2a: poll - 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.
Files
Off by default. With Accept A2A files (server role)
(a2a.) on, a client message may carry file parts besides its
text (ADR-284). Off, every part other than text/
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
rawpart (the bytes, base64 in the JSON) that names itsmedia, one ofType text/,plain application/,json application/,pdf image/andpng image/, 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 (jpeg -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 amediaand aType datapart are refused with-32005. A message that answers a waiting task carries text only. - File URLs
- A
urlpart with the samemediarules is accepted only from a host listed in Hosts A2A file URLs may come from (Type a2a.). Unlike the host list of the A2A client, an empty list admits no file URL at all (files. allowed Hosts -32005). The URL must be https and passes the address guard of ADR-202 when the task is accepted (-32602otherwise): 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.) 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 plainfiles. denied Hosts GETthat 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., 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 Raw Part Bytes max_, 16 MiB by default on MariaDB). The base64 text is measured before it is decoded. Larger isallowed_ packet -32602. While files are on, the largest request (a2a.) grows by the base64 size of this limit.server. max Request Bytes - Where a file goes
- Into a private store (
tx_), 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'snrllm_ a2a_ file rawis empty, itsmetadataunderhttps://names the file id, SHA-256 and size). Anr- llm. netresearch. de/ a2a/ ext/ file/ v1 urlpart 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 asrawwhile they fit together into Largest inline A2A artifact (a2a., 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 amax Inline Artifact Bytes urlto<endpoint>/, 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'sfiles/<file id> metadatanames the file id, SHA-256 and size as for an inbound file. A run kept at theredactedlevel 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_(groupfal_ file files), naming the file'ssys_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.file 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
fulllevel (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 (Fal). A file outside those mounts, a uid that no file carries and a run without a user get the same answer,Storage Gate:: is File Accessible () 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:): 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.consume
- Taking a client's file into FAL
-
A run stores a file the client sent with the task in FAL with the tool
adopt_(groupclient_ file files), naming the file by its number, the N of the line "File N of M from the client" the run received (ADR-305). 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
Localstorage 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 ownLocalstorage 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
WORKINGmeanwhile. 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_), 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.01. txt - 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
writesartifact of the task names the newsys_record in workspace 0: a FAL file has no draft.file - 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.
- 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
- Downloading a file
-
GET <endpoint>/with the client's bearer token returns the bytes with their type,files/<file id> Content-,Disposition: attachment X-andContent- Type- Options: nosniff Cache-. A file of another client, an unknown file, an expired one and one the task's artifacts no longer name all answer the sameControl: no- store 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>/with the bearer token returnsfiles/<file id>/ capability {"url": ..., "expires: a URL that reads this one file of this one client without the bearer token for 15 minutes.At": ...} 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
401and is logged and counted per source address together with failed bearer tokens, under the same limit (nrllm-, 10 failures per 15 minutes); over it the answer isa2a- auth 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
urlpart 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:also deletes every file older than Hours an A2A file is kept (privacy: purge a2a., 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.files. retention Hours
Limits and protection
- Proxy timeouts. A waiting request holds a PHP-FPM worker. Keep
a2a.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.server. blocking Wait Seconds - Waiting requests. At most
a2a.(default 4) blocking requests wait at the same time on the installation; one more is refused with HTTP 503,server. max Waiting Requests WAITING_. A request withCAPACITY_ EXHAUSTED returntakes no waiting slot.Immediately - Streams. A stream holds a PHP-FPM worker while it is open. At most
a2a.(default 2) streams read one task,server. max Streams Per Task a2a.(default 4) belong to one client, andserver. max Streams Per Client a2a.(default 8) are open on the installation; one more is refused with HTTP 503,server. max Streams STREAM_andCAPACITY_ EXHAUSTED Retry-, before anything is stored. A stream that dies without closing frees its slot within 30 seconds. An event larger thanAfter a2a.(default 1 MiB) is not sent; the stream ends and the client reads the task withserver. max Frame Bytes Get. 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.Task - Proxies in front of a stream. The response carries
X-andAccel- Buffering: 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 aControl: no- cache Subscribebefore relying on streams.To Task - Request size. A body above
a2a.(default 1 MiB, plus the base64 size ofserver. max Request Bytes a2a.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.max Raw Part Bytes - 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-; override it like TYPO3's own limiters ina2a- auth $GLOBALS. Behind a reverse proxy, name it in['TYPO3_ CONF_ VARS'] ['SYS'] ['rate Limiter'] ['nrllm- a2a- auth'] $GLOBALS; otherwise every client counts as the proxy's address and shares one limit.['TYPO3_ CONF_ VARS'] ['SYS'] ['reverse Proxy IP'] - Refusals name their reason (
error.holds adata google.) and, where a retry may help, arpc. Error Info Retry-header.After