Function Calls
The AI Context module provides three AI function call plugins grouped under
Context Tools (context_tools), registered via the
Drupal\ai_context\Plugin\AiFunctionGroup\ContextTools plugin. This group
label appears in AI module tool pickers alongside other function groups.
Plugins in this group:
ai_context:list_ai_context_itemsai_context:load_ai_context_item_by_idai_context:get_relevant_ai_context_items
Agents can invoke them as tools for context discovery, loading, and relevance-based selection.
Tools that should inherit the running agent ID when agent_id is
omitted implement AiContextInheritsAgentIdInterface.
GetRelevantAiContextItems and ListAiContextItems do;
LoadAiContextItemById does not.
All three plugins require the current user to have at least one of:
- Use Published AI Context in AI Features (
access published ai context) - View AI Context Items in CCC (
view ai context items) - Administer AI Context (
administer ai context)
See Configuration for how these permissions differ from CCC listing and editorial access.
Tool workflow
For agent-driven discovery, the typical flow is:
- List available items with
ai_context:list_ai_context_items - Load chosen items with
ai_context:load_ai_context_item_by_id
Alternatively, Get relevant (ai_context:get_relevant_ai_context_items)
runs the full selection pipeline in one step (scope scoring, subcontext
resolution, and rendering).
GetRelevantAiContextItems
Plugin ID: ai_context:get_relevant_ai_context_items
Function name: ai_context_get_relevant_ai_context_items
Class: Drupal\ai_context\Plugin\AiFunctionCall\GetRelevantAiContextItems
Selects and returns relevant context for a task using the same pipeline as
automatic system-prompt injection. Delegates to ai_context.selection_factory
(which runs the internal selector pipeline).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
task |
string |
Yes | Current task or user prompt to select context for |
scope_subscriptions |
object |
No | Scope plugin IDs and their subscribed value lists (e.g. {"language":["en"],"tag":["5"]}) |
always_include |
list |
No | Context item UUIDs (or leftover numeric IDs) to always include |
never_include |
list |
No | Context item UUIDs (or leftover numeric IDs) to never include |
agent_id |
string |
No | LLM-visible agent ID. Converted to the canonical consumer ID agent:{id} before config merge. When omitted during an agent run, the running agent is used |
selection_mode |
string |
No | minimal, relevant, or broad -- a nested ladder where each mode includes everything the one before it does. Omit to inherit the agent's saved mode when agent_id is set; otherwise the site-wide default applies (relevant unless changed). An explicit value overrides the agent. Unrecognized values fail validation |
entity_type |
string |
No | Entity type for contextual scope matching (e.g. node) |
entity_id |
integer |
No | Entity ID for contextual scope matching (used with entity_type) |
max_tokens |
integer |
No | Override for max tokens in rendered text |
Behavior
Builds an AiContextSelection from the parameters and returns the rendered
context text. If no items match, the output is
"No relevant context items found."
When agent_id is provided, that agent's saved consumer scope subscriptions,
always/never include lists, and limits are merged with explicit parameters.
Explicit scope values replace the same scope key, include lists are combined,
and explicit limits or selection_mode override agent values.
Exported consumer config stores those include lists as context item
UUIDs. Runtime selection still accepts leftover numeric IDs.
When the tool runs inside an agent and agent_id is omitted,
AiContextAgentToolSubscriber fills it from AgentToolPreExecuteEvent
before execute(). Saved subscriptions, include lists, and selection
mode are then merged the same way as an explicit ID. An explicit
agent_id still wins. Non-agent callers never fire that event, so they
keep consumer=none unless they pass an ID. Factory helpers
getResult() and getRenderedContext() accept an optional
$consumerId; omit it for a pull with no consumer. See
Page and entity context.
entity_type and entity_id are likewise optional. Without them,
entity-dependent scopes have no request entity to match. See
Page and entity context.
Example output
## Brand Guidelines
Use our primary brand color (#1a73e8) for all headings...
## Product Categories
Our catalog is organized into three main categories...
ListAiContextItems
Plugin ID: ai_context:list_ai_context_items
Function name: ai_context_list_ai_context_items
Class: Drupal\ai_context\Plugin\AiFunctionCall\ListAiContextItems
Lists published, accessible context items with ID, label, and purpose.
Intended as a lightweight discovery tool so agents can choose what to load
via LoadAiContextItemById. Does not return full item content.
Results are capped at 200 items (sorted by ID ascending).
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
scope_subscriptions |
object |
No | Filter by scope subscriptions |
agent_id |
string |
No | LLM-visible agent ID. Converted to agent:{id} before config merge. When omitted during an agent run, the running agent is used |
entity_type |
string |
No | Entity type for contextual scope matching |
entity_id |
integer |
No | Entity ID for contextual scope matching; used with entity_type |
Behavior
Loads published items the current user can view, then applies optional
filters via AiContextScopeResolver (hard context filters, scope
subscriptions, entity item filters, and consumer never/always include lists).
When the tool runs inside an agent and agent_id is omitted,
AiContextAgentToolSubscriber fills it from AgentToolPreExecuteEvent
before execute(), the same way as GetRelevantAiContextItems. An
explicit agent_id still wins. Non-agent callers never fire that event.
Example output
Available context items (3):
- [5] Brand Guidelines — Tone, voice, and visual identity rules
- [12] Product Categories — Catalog organization overview
- [3] Compliance Notes — Medical device regulatory context
LoadAiContextItemById
Plugin ID: ai_context:load_ai_context_item_by_id
Function name: ai_context_load_ai_context_item_by_id
Class: Drupal\ai_context\Plugin\AiFunctionCall\LoadAiContextItemById
Loads one or more context items by ID and returns fully rendered content. Use after listing items. Requested IDs appear in tool arguments for observability.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
context_item_ids |
list |
Yes | One or more numeric context item IDs |
task |
string |
No | Task description for conditional subcontext resolution |
max_tokens |
integer |
No | Max tokens override for rendered text |
include_subcontext |
boolean |
No | Include child items of loaded parents (default: true) |
Behavior
Loads published, accessible items by ID, translates them to the current
content language, optionally resolves subcontext children via
AiContextSubcontextResolver, and renders via AiContextRenderer within
the token limit.
If subcontext is disabled in module settings, child items are not included
regardless of include_subcontext. See Subcontext.
Example output
## Brand Guidelines
Use our primary brand color (#1a73e8) for all headings...