[feat] Expose a guarded host model invocation capability to extensions #5679

Background

DeerFlow extensions can currently:

• observe system model calls through SystemModelCallObserver;
• expose model tools through PluginContribution;
• access explicitly granted host capabilities through ExtensionRuntimeDeps.

However, an extension service cannot actively invoke a model already configured in DeerFlow.

This creates a general capability gap for extensions that need model-assisted processing outside an agent run, such as:

• classification and content transformation;
• structured information extraction;
• summarization;
• validation and quality evaluation;
• metadata generation;
• background processing triggered by extension-owned workflows.

Currently, an extension must configure its own provider credentials and duplicate parts of DeerFlow's model resolution, provider adaptation, authorization, timeout, and observability behavior.

Proposed capability

Expose an optional, host-provided model invocation capability through ExtensionRuntimeDeps.

Conceptually:

class ExtensionService:
    async def start(self, deps: ExtensionRuntimeDeps) -> None:
        self.model_invoker = deps.model_invoker

The public extension contract could use narrow, provider-neutral request and response types:

@dataclass(frozen=True)
class ModelInvocationRequest:
    messages: Sequence[ModelMessage]
    model_role: str | None = None
    purpose: str | None = None
    response_schema: Mapping[str, object] | None = None
    timeout_seconds: float | None = None


@dataclass(frozen=True)
class ModelInvocationResult:
    content: str
    structured_output: Mapping[str, object] | None = None
    resolved_model: str | None = None
    usage: ModelUsage | None = None

The exact types are open for discussion.

The important boundary is that extensions should not receive provider clients, API keys, the complete AppConfig, or internal model framework objects.

Model selection

The request should identify an optional logical model_role, rather than a deployment-specific model name.

For example, a deployment may define roles such as default, fast, or reasoning. The host maps an authorized role to a configured model. This allows operators to replace or reroute models without changing extension code.

If no role is supplied, the host may use the deployment-defined default extension or system model.

The extension should not supply arbitrary provider credentials or construct the host model directly.

Authorization

Model invocation should be an explicit, source-bound host capability, following the guarded capability pattern used by other extension runtime dependencies.

For example:

plugins:
  - name: example-extension
    use: example_package:install
    host_access:
      model_invocation:
        roles: [default]
        max_concurrency: 2

Possible host-enforced restrictions include:

• allowed logical model roles;
• maximum concurrency;
• timeout and output limits;
• optional purpose identifiers;
• revocation when the plugin grant or source changes.

The first implementation does not need to provide every quota mechanism, but the contract should allow the host to enforce policy without exposing credentials.

Host responsibilities

The host invocation implementation should retain responsibility for:

• resolving logical roles to configured models;
• provider construction and credentials;
• model authorization;
• timeout and cancellation;
• tracing and usage metadata;
• normalized errors;
• optional structured-output handling.

Initial scope

A minimal first version only needs:

• non-streaming asynchronous invocation;
• text messages;
• optional structured output;
• timeout and cancellation;
• explicit unavailable, unauthorized, and invocation-failed errors.

The following can remain out of scope initially:

• Agent or LangGraph execution;
• tool calling;
• token streaming;
• conversation persistence;
• direct access to provider SDKs;
• access to raw DeerFlow configuration or credentials.

Relationship to existing extension APIs

This differs from SystemModelCallObserver, which passively observes model calls initiated by the host.

It also differs from plugin ModelTool contributions, where an extension exposes a tool for a DeerFlow agent to invoke.

The proposed capability allows an authorized extension service to initiate a bounded model call while DeerFlow retains ownership of model configuration, credentials, routing, and policy enforcement.

Example

An extension receives extension-owned input and requests a structured transformation:

result = await model_invoker.invoke(
    ModelInvocationRequest(
        model_role="default",
        messages=[
            ModelMessage(
                role="user",
                content="Extract the requested fields from this content.",
            )
        ],
        response_schema={
            "type": "object",
            "properties": {
                "items": {
                    "type": "array",
                    "items": {"type": "string"},
                }
            },
            "required": ["items"],
        },
    )
)

The extension owns its workflow and persistence. DeerFlow owns model selection, credentials, authorization, and invocation behavior.

Compatibility

The capability should be optional:

• existing extensions remain unchanged;
• deps.model_invoker is absent or None when unsupported or not granted;
• deployments without extensions incur no model invocation overhead.

Open questions

1. Should logical model roles be built in, deployment-defined, or both?
2. Should structured output be included in the initial contract?
3. Which resource limits should be part of the public contract, and which should remain host implementation details?