Agent tools¶
The module ships two AI function call plugins in the AI Content Review tools group. They are how an agent reports a result, and they are the contract that makes an agent's answer parseable.
| Tool | ID | Function name |
|---|---|---|
| AI Content Review Result | ai_content_review:content_review_result |
ai_content_review_result |
| AI Content Review Suggestion Item | ai_content_review:suggestion_item |
ai_content_review_suggestion_item |
AI Content Review Result¶
The tool every agent used by a criterion must carry. The criterion's agent select only offers agents that include it, so an agent without it cannot be chosen.
| Argument | Meaning |
|---|---|
status |
complete when the review ran, skipped when the criterion did not apply, failed when it could not be completed. |
score |
0 to 100, where 100 is perfect. Always sent. Use 0 for skipped and failed, where it is ignored. |
severity |
info for minor suggestions, warning for moderate issues, critical for blocking problems. Omitted for skipped and failed. |
explanation |
Human-readable account of what was checked and why the score was given. |
suggestions |
An array of suggestion objects, empty when there are none. |
The agent calls it exactly once per review.
AI Content Review Suggestion Item¶
A schema reference rather than a callable step. It documents the shape of one element of
suggestions[], so an agent that has it attached knows what to put there. Agents should not call it
directly.
| Field | Meaning |
|---|---|
type |
A suggestion plugin ID, which decides how the suggestion is applied. The argument lists every plugin with its label and description, so the agent knows what each type does. See Suggestion plugins. |
target |
The field machine name, for example body or field_summary, optionally followed by : and the item's delta for a field with several values, for example field_notes:1 (see Targets). null for entity-level findings. |
original_value |
The exact current value to replace, or null. |
suggested_value |
The replacement, or null. |
rationale |
Why the change is proposed. Required. |
Targets¶
A suggestion's target names the field it is about, and original_value quotes the passage in it.
body: the quote is looked for in every item of the field. If it occurs more than once, the suggestion is refused as ambiguous.field_notes:1: the quote is looked for only in the item with that delta. The delta counts from 0, so:0is the first item and:1the second. The subject gives every<field>element atargetattribute holding exactly this value (field_notes:1for an item of a field with several, the bare name otherwise), and the agent copies it.
A quote that is not in the named item is not applied, even when another item holds it. A delta that is not a non-negative integer is refused.
A delta is a position in the reviewed revision. Applying a suggestion can remove an item (Drupal drops a string item that is left empty), and the items after it move up, so a delta is only used while the target field holds what it held at the review. Changes to other fields, such as applying a suggestion to the body, do not matter. Once the field itself has changed, the quote is looked for in every item of the field and has to occur once: a shifted delta can then never write to the wrong item, and a passage that is now in two items is refused as ambiguous. A delta past the last item is refused as the AI's error.
The response contract¶
The two tools together produce this:
{
"status": "complete",
"score": 85,
"severity": "info",
"explanation": "Plain language result, or the reason for skipping or failing.",
"suggestions": [
{
"type": "text_replace",
"target": "body",
"original_value": "Current field content.",
"suggested_value": "Improved field content.",
"rationale": "The current wording is passive; the revision uses active voice."
}
]
}
scoreandseveritymay be null forskippedandfailed.suggestionsmay be an empty array.targetmay be null for findings not tied to one field.
A response that does not conform produces a Review Record with status = failed, holding the raw
response in its error message for debugging. Nothing is discarded.
What the criterion sends¶
AgentBasedCriterion compiles one task message per run:
- The criterion's Guidelines & rules, verbatim.
- The Evaluation examples, compiled to markdown, each group's label sent as an aspect to weigh.
- The subject, fenced, from the record type's
buildReviewContext().
For an internal record the subject is the entity's type, bundle and label, then each text field
with its current value exactly as stored, between <field> tags that give its name, label and
type. That is what a suggestion's target and original_value are copied from. Empty text fields
are listed and marked empty. A formatted field whose text format escapes markup, such as core's
Plain text, is marked html="false": the agent is asked to quote and rewrite it as text, and Apply
runs no markup checks on it. Fields that hold no text a suggestion can change are not listed at
all. Values are read from the translation the record reviewed. The entity's keys and revision
metadata are left out, as is any field the user running the review may not view.
A text field is one of the field types in Target\TextFields: string, string_long, text,
text_long and text_with_summary. Apply accepts the same list, so the agent is never shown a
field it cannot write to. Types that extend the string item class but are not prose, such as uri,
file_uri, uuid and password, are not text fields.
The subject is fenced with apostrophes, one more than the longest run inside it, so a value is never rewritten on its way to the agent and a quote of it still matches the stored text.
Images and embedded entities in those values (an <img>, or an element such as <drupal-media>
that names an entity by data-entity-uuid; links are not embeds) are shown as tokens,
{{embed:1}}, {{embed:2}}, numbered per field. The agent keeps a token in place rather than
copying a long tag, and before its suggestions are stored, the record type's restoreEmbeds() swaps
each token back for exactly the markup it stood for, rebuilt from the reviewed revision.
The compiled prompt is sent to the agent as its chat message, not only as a task: ai_agents
builds a task's message with strip_tags(), which would remove the <field> markers and the HTML
of formatted fields.
When writing an agent for a review rule:
- Do not pass the reviewed entity's text fields through tokens such as
[node:body]. They are already in the subject, as stored, and a token renders the body through its text format, so a quote copied from it may not match what is stored. Tokens are still the way to pass metadata the subject does not carry, such as dates and referenced entity names. - Ask for formatted text to be quoted and rewritten as HTML. Instructions to quote "the rendered page" or plain text make suggestions whose quote is not in the stored value. The module does not guess which stretch of the HTML was meant, so such a suggestion is refused and the editor has to apply it by hand.
Token contexts come from the record type's getTokenContexts() merged with the agent's own, so an
agent working on an internal record can read and write the live entity's fields through its other
tools.
Thresholds are never sent. Drupal applies them to the returned score.
Adding your own tool¶
Tools are drupal/ai function call plugins. Put a class carrying #[FunctionCall] in
src/Plugin/AiFunctionCall/ and set group: 'ai_content_review' to have it appear alongside these
two in the tools library. It will then be attachable to any agent from the AI Agents UI.