Skip to content

Code reference

These references are generated from Python source without importing Nautobot or starting the app. They describe implementation interfaces, not a separate supported public SDK or REST API.

App configuration

nautobot_agent

App declaration for nautobot_agent.

NautobotAgentConfig

Bases: NautobotAppConfig

App configuration for the nautobot_agent app.

Source code in nautobot_agent/__init__.py
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
class NautobotAgentConfig(NautobotAppConfig):
    """App configuration for the nautobot_agent app."""

    name = "nautobot_agent"
    verbose_name = "Nautobot Agent"
    version = __version__
    author = "Geury Torres"
    description = "AI agent integration for Nautobot."
    base_url = "nautobot-agent"

    def ready(self):
        """Register the app, validate deployment settings and dependency pins, and prime source discovery."""
        super().ready()
        # Imported lazily so that importing the app package does not load the agent stack.
        from nautobot_agent.sources.source_access import (  # pylint: disable=import-outside-toplevel
            initialize_agent_security,
        )

        initialize_agent_security()

        app_settings.validate_all()

ready()

Register the app, validate deployment settings and dependency pins, and prime source discovery.

Source code in nautobot_agent/__init__.py
23
24
25
26
27
28
29
30
31
32
33
def ready(self):
    """Register the app, validate deployment settings and dependency pins, and prime source discovery."""
    super().ready()
    # Imported lazily so that importing the app package does not load the agent stack.
    from nautobot_agent.sources.source_access import (  # pylint: disable=import-outside-toplevel
        initialize_agent_security,
    )

    initialize_agent_security()

    app_settings.validate_all()

Deployment settings

nautobot_agent.app_settings

Deployment validation, including profile catalogs whose values are read at use time and never logged.

ChatRunSettings dataclass

Validated deployment policy and task budgets for durable chat runs.

Source code in nautobot_agent/app_settings.py
345
346
347
348
349
350
351
352
353
@dataclass(frozen=True)
class ChatRunSettings:
    """Validated deployment policy and task budgets for durable chat runs."""

    celery_queue: str | None
    soft_time_limit: int
    hard_time_limit: int
    cleanup_timeout: int
    queue_wait_timeout: int

InterpreterLimits dataclass

Validated limits for one stateless Monty execution.

max_duration_secs bounds interpreter execution across the submitted feed, including its resumptions. Time spent waiting on host calls is excluded, so it is neither a total wall-time deadline nor a CPU-clock limit; SQL statement timeouts and run limits still apply. max_memory_bytes bounds interpreter memory, max_host_calls the host-tool calls per execution, and max_output_chars the returned result size.

Source code in nautobot_agent/app_settings.py
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
@dataclass(frozen=True)
class InterpreterLimits:
    """Validated limits for one stateless Monty execution.

    ``max_duration_secs`` bounds interpreter execution across the submitted feed,
    including its resumptions. Time spent waiting on host calls is excluded, so it is
    neither a total wall-time deadline nor a CPU-clock limit; SQL statement timeouts and
    run limits still apply. ``max_memory_bytes`` bounds interpreter memory,
    ``max_host_calls`` the host-tool calls per execution, and ``max_output_chars`` the
    returned result size.
    """

    max_duration_secs: float
    max_memory_bytes: int
    max_host_calls: int
    max_output_chars: int

ScopeMode

Bases: StrEnum

Deployment-owned policy for the pre-send scope gate.

Source code in nautobot_agent/app_settings.py
166
167
168
169
170
171
class ScopeMode(StrEnum):
    """Deployment-owned policy for the pre-send scope gate."""

    STRICT = "strict"
    CONVERSATION = "conversation"
    OFF = "off"

blocked_models()

Return canonical, deduplicated blocked model labels without querying the database.

Source code in nautobot_agent/app_settings.py
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
def blocked_models() -> tuple[str, ...]:
    """Return canonical, deduplicated blocked model labels without querying the database."""
    app_config = _app_config(_BLOCKED_MODELS_DIAGNOSTIC)
    configured = app_config.get("blocked_models", DEFAULTS["blocked_models"])
    if not isinstance(configured, list):
        raise ImproperlyConfigured(_BLOCKED_MODELS_DIAGNOSTIC)

    if not configured:
        return ()
    registry = {config.label.lower(): config for config in apps.get_app_configs()}
    normalized = []
    for label in configured:
        if not isinstance(label, str) or label.count(".") != 1:
            raise ImproperlyConfigured(_BLOCKED_MODELS_DIAGNOSTIC)
        app_label, model_name = label.lower().split(".")
        config = registry.get(app_label)
        try:
            model = config.get_model(model_name) if config is not None else None
        except LookupError:
            model = None
        if model is None:
            raise ImproperlyConfigured(_BLOCKED_MODELS_DIAGNOSTIC)
        if model._meta.swapped:
            replacement = model._meta.swapped
            raise ImproperlyConfigured(
                f"PLUGINS_CONFIG['nautobot_agent']['blocked_models'] names a swapped model; configure its replacement "
                f"'{replacement}' instead."
            )
        if model._meta.proxy:
            raise ImproperlyConfigured(
                "PLUGINS_CONFIG['nautobot_agent']['blocked_models'] cannot name a proxy model; configure its concrete "
                f"model '{model._meta.concrete_model._meta.label}' instead."
            )
        normalized.append(model._meta.label)
    return tuple(dict.fromkeys(normalized))

builtin_skills_enabled()

Return whether packaged skills are included in runtime snapshots.

Source code in nautobot_agent/app_settings.py
192
193
194
195
196
197
198
def builtin_skills_enabled() -> bool:
    """Return whether packaged skills are included in runtime snapshots."""
    app_config = _app_config(_BUILTIN_SKILLS_DIAGNOSTIC)
    value = app_config.get("builtin_skills", DEFAULTS["builtin_skills"])
    if not isinstance(value, bool):
        raise ImproperlyConfigured(_BUILTIN_SKILLS_DIAGNOSTIC)
    return value

chat_max_model_calls()

Return the configured per-run logical model-call ceiling.

Source code in nautobot_agent/app_settings.py
65
66
67
def chat_max_model_calls() -> int:
    """Return the configured per-run logical model-call ceiling."""
    return _positive_setting("chat_max_model_calls")

chat_max_tool_calls()

Return the configured per-run graph tool-call ceiling.

Source code in nautobot_agent/app_settings.py
80
81
82
def chat_max_tool_calls() -> int:
    """Return the configured per-run graph tool-call ceiling."""
    return _positive_setting("chat_max_tool_calls")

chat_return_timeout()

Return the configured delay before an ordinary departure expires selection.

Source code in nautobot_agent/app_settings.py
85
86
87
def chat_return_timeout() -> int:
    """Return the configured delay before an ordinary departure expires selection."""
    return _positive_setting("chat_return_timeout")

chat_run_settings()

Validate chat run queue and task budgets without database or worker access.

Source code in nautobot_agent/app_settings.py
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
def chat_run_settings() -> ChatRunSettings:
    """Validate chat run queue and task budgets without database or worker access."""
    app_config = _app_config(_CHAT_RUN_DIAGNOSTIC)
    values = {key: app_config.get(key, DEFAULTS[key]) for key in _CHAT_RUN_SETTING_KEYS}
    queue = values["chat_celery_queue"]
    if queue is not None and (not isinstance(queue, str) or not queue.strip()):
        raise ImproperlyConfigured(_CHAT_RUN_DIAGNOSTIC)
    integer_values: dict[str, int] = {}
    for key in _CHAT_RUN_SETTING_KEYS:
        if key == "chat_celery_queue":
            continue
        integer_values[key] = _positive_int(values[key], _CHAT_RUN_DIAGNOSTIC)
        if integer_values[key] > 2_147_483_647:
            raise ImproperlyConfigured(_CHAT_RUN_DIAGNOSTIC)
    if (
        integer_values["chat_soft_time_limit"] + integer_values["chat_cleanup_timeout"] + CHAT_RUN_SHUTDOWN_MARGIN
        >= integer_values["chat_hard_time_limit"]
    ):
        raise ImproperlyConfigured(_CHAT_RUN_DIAGNOSTIC)
    return ChatRunSettings(
        celery_queue=queue.strip() if queue is not None else None,
        soft_time_limit=integer_values["chat_soft_time_limit"],
        hard_time_limit=integer_values["chat_hard_time_limit"],
        cleanup_timeout=integer_values["chat_cleanup_timeout"],
        queue_wait_timeout=integer_values["chat_queue_wait_timeout"],
    )

credential_profiles()

Return fresh validated LLM credential profiles; provider values are intentionally unconstrained.

Source code in nautobot_agent/app_settings.py
250
251
252
def credential_profiles() -> dict[str, dict[str, Any]]:
    """Return fresh validated LLM credential profiles; provider values are intentionally unconstrained."""
    return _profile_catalog("credentials", _CREDENTIAL_PROFILES_DIAGNOSTIC, lambda key, _value: bool(key.strip()))

interpreter_limits()

Return merged, validated interpreter limits without exposing configured values.

Source code in nautobot_agent/app_settings.py
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
def interpreter_limits() -> InterpreterLimits:
    """Return merged, validated interpreter limits without exposing configured values."""
    app_config = _app_config(_INTERPRETER_DIAGNOSTIC)
    configured = app_config.get("interpreter", {})
    if not isinstance(configured, dict) or set(configured).difference(_INTERPRETER_DEFAULTS):
        raise ImproperlyConfigured(_INTERPRETER_DIAGNOSTIC)
    values = _INTERPRETER_DEFAULTS | configured
    duration = values["max_duration_secs"]
    try:
        valid_duration = (
            not isinstance(duration, bool)
            and isinstance(duration, int | float)
            and duration > 0
            and math.isfinite(duration)
        )
    except (OverflowError, TypeError, ValueError):
        valid_duration = False
    if not valid_duration:
        raise ImproperlyConfigured(_INTERPRETER_DIAGNOSTIC)
    integer_limits: dict[str, int] = {}
    for key in ("max_memory_bytes", "max_host_calls", "max_output_chars"):
        integer_limits[key] = _positive_int(values[key], _INTERPRETER_DIAGNOSTIC)
    if integer_limits["max_output_chars"] < 1000:
        raise ImproperlyConfigured(_INTERPRETER_DIAGNOSTIC)
    return InterpreterLimits(
        max_duration_secs=float(duration),
        max_memory_bytes=integer_limits["max_memory_bytes"],
        max_host_calls=integer_limits["max_host_calls"],
        max_output_chars=integer_limits["max_output_chars"],
    )

mcp_credential_profiles()

Return fresh validated HTTP-header profiles without exposing their values to forms.

Source code in nautobot_agent/app_settings.py
255
256
257
258
259
260
261
262
263
def mcp_credential_profiles() -> dict[str, dict[str, str | None]]:
    """Return fresh validated HTTP-header profiles without exposing their values to forms."""

    def valid_header(key, value):
        return _HEADER_NAME.fullmatch(key) is not None and (
            value is None or (isinstance(value, str) and "\r" not in value and "\n" not in value)
        )

    return _profile_catalog("mcp_credentials", _MCP_CREDENTIAL_PROFILES_DIAGNOSTIC, valid_header)

mcp_environment_profiles()

Return fresh validated stdio environment profiles without exposing their values to forms.

Source code in nautobot_agent/app_settings.py
277
278
279
def mcp_environment_profiles() -> dict[str, dict[str, str | None]]:
    """Return fresh validated stdio environment profiles without exposing their values to forms."""
    return _profile_catalog("mcp_environments", _MCP_ENVIRONMENT_PROFILES_DIAGNOSTIC, valid_mcp_environment_entry)

query_limits()

Return the validated query-response byte ceiling without exposing configured values.

Source code in nautobot_agent/app_settings.py
397
398
399
400
401
402
403
404
405
def query_limits() -> int:
    """Return the validated query-response byte ceiling without exposing configured values."""
    app_config = _app_config(_QUERY_LIMIT_DIAGNOSTIC)
    configured = app_config.get("query", {})
    if not isinstance(configured, dict) or set(configured).difference({"max_page_bytes"}):
        raise ImproperlyConfigured(_QUERY_LIMIT_DIAGNOSTIC)
    return _positive_int(
        configured.get("max_page_bytes", DEFAULTS["query"]["max_page_bytes"]), _QUERY_LIMIT_DIAGNOSTIC, 1024
    )

query_statement_timeout_ms()

Return the database-side time limit for each live-data SQL statement.

Source code in nautobot_agent/app_settings.py
70
71
72
73
74
75
76
77
def query_statement_timeout_ms() -> int:
    """Return the database-side time limit for each live-data SQL statement."""
    timeout = _positive_setting("query_statement_timeout_ms")
    if timeout > 2_147_483_647:
        raise ImproperlyConfigured(
            "PLUGINS_CONFIG['nautobot_agent']['query_statement_timeout_ms'] must not exceed 2147483647."
        )
    return timeout

scope_mode()

Return the validated, uncached deployment scope policy.

Source code in nautobot_agent/app_settings.py
177
178
179
180
181
182
183
184
185
186
def scope_mode() -> ScopeMode:
    """Return the validated, uncached deployment scope policy."""
    app_config = _app_config(_SCOPE_MODE_DIAGNOSTIC)
    value = app_config.get("scope_mode", DEFAULTS["scope_mode"])
    if not isinstance(value, str):
        raise ImproperlyConfigured(_SCOPE_MODE_DIAGNOSTIC)
    try:
        return ScopeMode(value)
    except ValueError:
        raise ImproperlyConfigured(_SCOPE_MODE_DIAGNOSTIC) from None

source_apps_by_group()

Validate and normalize the deployment-owned group-to-package mapping.

Source code in nautobot_agent/app_settings.py
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
def source_apps_by_group() -> dict[str, tuple[str, ...]]:
    """Validate and normalize the deployment-owned group-to-package mapping."""
    app_config = _app_config(_SOURCE_APPS_BY_GROUP_DIAGNOSTIC)
    mapping = app_config.get("source_apps_by_group", DEFAULTS["source_apps_by_group"])
    if not isinstance(mapping, dict):
        raise ImproperlyConfigured(_SOURCE_APPS_BY_GROUP_DIAGNOSTIC)
    normalized = {}
    for group_name, packages in mapping.items():
        if not isinstance(group_name, str) or not group_name.strip() or not isinstance(packages, list):
            raise ImproperlyConfigured(_SOURCE_APPS_BY_GROUP_DIAGNOSTIC)
        if any(
            not isinstance(package, str)
            or not package.strip()
            or any(not part.isidentifier() or iskeyword(part) for part in package.split("."))
            for package in packages
        ):
            raise ImproperlyConfigured(_SOURCE_APPS_BY_GROUP_DIAGNOSTIC)
        normalized[group_name] = tuple(dict.fromkeys(packages))
    return normalized

tracing_enabled()

Return whether execution tracing is enabled, requiring an explicit boolean value.

Source code in nautobot_agent/app_settings.py
204
205
206
207
208
209
210
def tracing_enabled() -> bool:
    """Return whether execution tracing is enabled, requiring an explicit boolean value."""
    app_config = _app_config(_TRACING_DIAGNOSTIC)
    value = app_config.get("tracing", DEFAULTS["tracing"])
    if not isinstance(value, bool):
        raise ImproperlyConfigured(_TRACING_DIAGNOSTIC)
    return value

valid_mcp_environment_entry(key, value)

Validate an environment entry; catalogs allow null placeholders, but selected profiles must be fully set.

Source code in nautobot_agent/app_settings.py
266
267
268
269
270
271
272
273
274
def valid_mcp_environment_entry(key, value) -> bool:
    """Validate an environment entry; catalogs allow null placeholders, but selected profiles must be fully set."""
    return (
        isinstance(key, str)
        and bool(key)
        and "=" not in key
        and "\x00" not in key
        and (value is None or (isinstance(value, str) and "\x00" not in value))
    )

validate_all()

Run every deployment setting reader; keep each reader's diagnostics explicit.

Source code in nautobot_agent/app_settings.py
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
def validate_all() -> None:
    """Run every deployment setting reader; keep each reader's diagnostics explicit."""
    configured = _app_config("PLUGINS_CONFIG['nautobot_agent'] must be a dict.")
    unknown = set(configured).difference(DEFAULTS)
    if unknown:
        names = ", ".join(sorted(str(key) for key in unknown))
        raise ImproperlyConfigured(f"PLUGINS_CONFIG['nautobot_agent'] contains unknown settings: {names}.")
    interpreter_limits()
    scope_mode()
    builtin_skills_enabled()
    tracing_enabled()
    credential_profiles()
    mcp_credential_profiles()
    mcp_environment_profiles()
    blocked_models()
    source_apps_by_group()
    chat_run_settings()
    query_limits()
    query_statement_timeout_ms()
    chat_return_timeout()
    chat_max_model_calls()
    chat_max_tool_calls()