Skip to content

Extending

Add a vocabulary

A vocabulary is a serializer plugin: a class in a module's src/Plugin/AgentSurfaceSerializer directory with the #[AgentSurfaceSerializer] attribute, implementing Drupal\agent_surface\Serializer\SerializerInterface. Extend SerializerPluginBase, which returns nothing for each carrier, and override the carriers the vocabulary defines.

The module's own categories (training, inference, search, automated) are deliberately no specification's spelling. Translating them is the plugin's job, so a revised vocabulary is a new plugin rather than a change to stored configuration, and both can be enabled during a transition.

<?php

declare(strict_types=1);

namespace Drupal\my_module\Plugin\AgentSurfaceSerializer;

use Drupal\agent_surface\Attribute\AgentSurfaceSerializer;
use Drupal\agent_surface\Serializer\SerializerPluginBase;
use Drupal\agent_surface\Signal\Category;
use Drupal\agent_surface\Signal\Preference;
use Drupal\agent_surface\Signal\SignalSet;
use Drupal\Core\StringTranslation\TranslatableMarkup;

#[AgentSurfaceSerializer(
  id: 'example_training',
  label: new TranslatableMarkup('Example training header'),
  spec_version: 'Example spec, draft 1',
  description: new TranslatableMarkup('An X-Example-Training header.'),
)]
final class ExampleTraining extends SerializerPluginBase {

  public function toHeaders(SignalSet $signals): array {
    return match ($signals->get(Category::Training)) {
      Preference::Allow => ['X-Example-Training' => 'yes'],
      Preference::Disallow => ['X-Example-Training' => 'no'],
      Preference::Unstated => [],
    };
  }

}
Method Returns
toHeaders(SignalSet $signals) Header values keyed by header name. A value may be a list for repeatable headers such as Link. An empty array when nothing is stated.
toRobotsLines(SignalSet $signals, ?string $path = NULL) Complete robots.txt lines. $path is a path prefix to scope the rule to; return nothing for a path if the specification has no path-scoped form.
toFrontMatter(SignalSet $signals) Front matter values keyed by key.

New plugins appear under Vocabularies to emit on the settings form; nothing is emitted until a site enables them there. Plugin definitions can be altered with hook_agent_surface_serializer_info_alter().

Hooks

Defined in agent_surface.api.php.

hook_agent_surface_headers_alter(array &$headers, SignalSet $signals, array $context)
Alters the response headers built for a signal set. $headers maps header names to lists of values. $context may contain entity, request and response.
hook_agent_surface_robots_lines_alter(array &$lines, SignalSet $signals, ?string $path)
Alters the robots.txt lines built for a signal set. $path is the prefix the lines are scoped to, or NULL for the whole site.
hook_agent_surface_front_matter_alter(array &$keys, SignalSet $signals, array $context)
Alters the front matter keys built for a signal set. $context may contain entity.
hook_agent_surface_serializer_info_alter(array &$definitions)
Alters serializer plugin definitions, keyed by plugin ID.
hook_agent_surface_declarations_changed()
Invoked after a declared signal changed and every cache tag carrying one was invalidated. For refreshing copies kept outside Drupal's cache.
hook_agent_surface_audit_alter(array &$build)
Alters the render array of the declared usage signals page.
hook_agent_surface_report_alter(array &$build, int $since)
Alters the render array of the request report. $since is the Unix timestamp the report starts from.

The submodules define their own, in their .api.php files:

hook_agent_surface_llmstxt_lines_alter(array &$lines)
Alters the Markdown lines agent_surface_llmstxt appends to llms.txt.
hook_agent_surface_rsl_license_alter(\DOMDocument $document, SignalSet $defaults)
Alters the RSL document agent_surface_rsl serves at /license.xml.

Hook implementations in this module are #[Hook] methods on the classes in src/Hook. While the module supports Drupal 10, each has a procedural #[LegacyHook] twin in the .module file that delegates to it.

Overriding services

No service, plugin, controller or form class is final, and their members are protected, so a site can decorate a service or swap a class through hook_agent_surface_serializer_info_alter() or a route subscriber.

function my_module_agent_surface_headers_alter(array &$headers, SignalSet $signals, array $context): void {
  $headers['X-Usage-Policy'][] = 'https://example.com/ai-policy';
}

Services

Service Class Use
agent_surface.signal_resolver Signal\SignalResolver The effective signals for the site (siteDefaults()), a bundle (forBundle()) or an entity (forEntity()), and their cacheability.
agent_surface.declarations Declaration\DeclarationBuilder Runs the enabled serializers: headers(), robotsLines(), frontMatter().
agent_surface.markdown_url_builder Url\MarkdownUrlBuilder The .md URL of an entity or the current page, or NULL when there is none.
plugin.manager.agent_surface_serializer Serializer\SerializerManager Serializer plugin discovery.

Cache tag

agent_surface_declarations is invalidated whenever a declared signal changes: on settings saves (through any route, configuration import included), on bundle override changes, and when modules are installed or uninstalled. Anything that renders a declaration should depend on it, and on config:agent_surface.settings; SignalResolver::cacheability() returns both, plus the bundle override's own tag for an entity.

Request attributes

During a request, $request->attributes->get('_agent_surface_rule') (AgentSurface::RULE_ATTRIBUTE) holds the rule that selected Markdown: suffix, format, accept or user_agent, or nothing for HTML. AgentSurface::isShareable() says whether a response for that rule may enter a shared cache.