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_items
ai_context:load_ai_context_item_by_id
ai_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 consumer ID when consumer_id is omitted implement AiContextInheritsConsumerIdInterface. 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. Builds a selection with fromParameters() and runs it with getResultFromSelection().

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. Context Tags and Taxonomy Terms values are taxonomy term UUIDs (e.g. `{"language":["en"],"tag":["7a1e8432-3616-438e-a411-76c93afba733"]}`)
`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
`consumer_id`	`string`	No	Canonical consumer ID (for example `agent:my_agent`). Formerly `agent_id`. When omitted during an agent run, the running agent is used as `agent:{id}`. Non-canonical values are ignored
`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 consumer's saved mode when `consumer_id` is set; otherwise the site-wide default applies (`relevant` unless changed). An explicit value overrides the consumer
`entity_type`	`string`	No	Entity type for contextual scope matching (e.g. `node`)
`entity_id`	`string` or `integer`	No	Entity ID for contextual scope matching (used with `entity_type`). Numeric IDs and machine-name IDs are valid. Other types are ignored
`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 consumer_id is provided, that consumer's saved 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 consumer values. Exported consumer config stores those include lists as context item UUIDs. Runtime selection still accepts leftover numeric IDs.

Get Relevant still constrains selection_mode with Choice (minimal, relevant, broad). An unrecognized tool-call value, including leftover match_all, can fail AI Agents validation before fromArray() runs. Direct fromArray() callers drop unrecognized string modes to NULL and inherit the consumer or site default. The no-throw path is only for those direct callers.

When the tool runs inside an agent and consumer_id is omitted, AiContextAgentToolSubscriber fills it from AgentToolPreExecuteEvent before execute() as agent:{running agent}. Saved subscriptions, include lists, and selection mode are then merged the same way as an explicit ID. An explicit canonical consumer_id still wins. A non-empty non-canonical value is replaced the same way as omitted and logged at debug. Non-agent callers never fire that event, so they keep consumer=none unless they pass an ID. getResult() and getRenderedContext() still leave consumerId null for non-agent callers. See Page and entity context.

entity_type and entity_id are likewise optional. Without them, entity-dependent scopes have no request entity to match. entity_id accepts a numeric ID or a machine-name ID. Other types are dropped, matching fromArray(). 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
`consumer_id`	`string`	No	Canonical consumer ID (for example `agent:my_agent`). Formerly `agent_id`. When omitted during an agent run, the running agent is used as `agent:{id}`
`entity_type`	`string`	No	Entity type for contextual scope matching
`entity_id`	`string` or `integer`	No	Entity ID for contextual scope matching; used with `entity_type`. Numeric IDs and machine-name IDs are valid. Other types are ignored

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 consumer_id is omitted, AiContextAgentToolSubscriber fills it from AgentToolPreExecuteEvent before execute(), the same way as GetRelevantAiContextItems. An explicit canonical consumer_id still wins. A non-empty non-canonical value is replaced the same way as omitted and logged at debug. 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...