Introducing a new way to review your PRs.

Read the announcement

usestrix / strix

Open-source AI penetration testing tool to find and fix your app’s vulnerabilities.

View on GitHub

26 documents · Updated Nov 20, 2026

docs / agent-factory-and-prompts

Agent factory and prompts

The agent factory creates the active agents for an authorized Strix scan. It combines each agent's role, scan settings, selected skills, operating tools, and model-facing instructions so the agent orchestration system can run one aligned scan across the root agent and its specialists.

Agent roles

Root agent

The root agent controls the scan. Its model instructions make it delegate hands-on testing, track scope and coverage, monitor specialists, and combine validated results into the final outcome. It must not perform reconnaissance or vulnerability testing itself. It has one explicit scan completion action, finish_scan, so text alone cannot end the scan.

References: strix/…/system_prompt.jinja• L3-10 strix/…/factory.py• L663-754 strix/…/root_agent.md• L6-17

Specialist agents

Specialist agents perform focused work for the root agent or another parent. A child receives a task, a name, selected skills, and optional inherited history. It returns its result with agent_finish, which completes the child task but not the wider scan.

References: strix/…/tools.py• L407-454 strix/…/execution.py• L303-364 strix/…/factory.py• L757-790

Prompt composition

Prompt layers

The model-facing system prompt has a stable policy layer and a run-specific layer. The stable layer explains authorized validation, communication, testing method, agent roles, coordination, reporting discipline, and available resources. The run-specific layer adds the scan mode, target context, selected knowledge, role, interaction mode, and available external connections.

The same composition path serves the root and child agents. Their roles and run settings change the final prompt. A caller can also replace the rendered prompt for one agent with instructions_override. The scan runner then pairs the prompt with the agent's tools and selected model.

References: strix/…/prompt.py• L74-125 strix/…/system_prompt.jinja• L1-18 strix/…/system_prompt.jinja• L68-161 strix/…/system_prompt.jinja• L200-241 strix/…/system_prompt.jinja• L282-429 strix/…/system_prompt.jinja• L508-543 strix/…/runner.py• L275-315 strix/…/factory.py• L693-705

Prompt assets

Prompt assets are reusable text packages that add focused knowledge to an agent. A skill is a Markdown knowledge package with optional metadata. The skill system resolves custom assets before packaged assets and supplies their content to the prompt.

The factory places caller-selected skills first. It then adds scan-mode and optional diff-scope guidance. Always-on browser, Python, counterevidence, and severity guidance follows. Root agents also receive orchestration guidance. White-box agents receive source-aware guidance. Duplicate skill names keep their first position.

The system prompt separates knowledge shared by sibling agents from knowledge requested for one agent. Shared knowledge and the available skill catalog appear before a cache point. Requested specialist knowledge appears after that point. This lets sibling prompts reuse their common prefix while keeping each agent's focused instructions distinct.

References: strix/…/__init__.py• L30-57 strix/…/__init__.py• L161-177 strix/…/__init__.py• L263-299 strix/…/prompt.py• L20-71 strix/…/system_prompt.jinja• L508-539

Scope context

Scope context tells the model which user instructions and targets govern the current scan. The prompt identifies the user as an authorized tester and includes the starting target list when one exists. The user can add or remove targets through later instructions, while websites, files, and tool output cannot change the scope. The scope asset is included after a cache point so run-specific context stays separate from reusable prompt content.

When external Model Context Protocol (MCP) connections are available, the same scope asset gives the model a controlled discovery path. It must list connections, search for a focused tool, inspect that tool's schema, and then call it. A full connection catalog is only a fallback when targeted search cannot identify the needed tool.

References: strix/…/scope.jinja• L1-34 strix/…/system_prompt.jinja• L530-543 strix/…/inputs.py• L192-226 strix/…/runner.py• L66-109 strix/…/runner.py• L294-334

Configured capabilities

Scan configuration

Scan configuration sets the operating posture of the active agents. Scan mode supplies the testing approach. Diff scope adds change-set guidance. Target type selects source-aware guidance. Requested skills focus the agent's knowledge. These settings shape the agent's direction rather than create separate agent classes.

The runner passes the same scan-wide mode, diff scope, and white-box status to the root and child builders. Each child can still receive a different focused skill set while remaining part of the same scan.

References: strix/…/runner.py• L261-266 strix/…/runner.py• L305-334 strix/…/factory.py• L663-705 strix/…/factory.py• L757-790

Operating capabilities

Capabilities give an agent ways to act in the scan sandbox. Every active agent receives filesystem and shell access for authorized inspection and checks. The factory also provides shared scan tools for planning, notes, coverage, threat modeling, web research, proxy work, external connections, reporting, and agent coordination.

The factory adapts these tool interfaces to the selected model route. It can adjust schema strictness, normalize structured arguments, decode shell input, and bound tool output before it enters the model's history. These rules keep the model-facing contract stable while the underlying tool protocol varies.

Registered tools extend every later agent. Per-call tools extend only the agent being built. Interactive agents also receive a tool that can return control to the user.

References: strix/…/factory.py• L92-337 strix/…/factory.py• L429-512 strix/…/factory.py• L574-660 strix/…/factory.py• L707-753

Capability alignment

The active scanning agent is the combined contract of its prompt, capabilities, tools, and runtime context. A skill does not grant a new power by itself. A capability does not define the agent's purpose. The factory makes the combination useful by matching each role and task with the needed guidance and actions.

For example, a root agent needs orchestration guidance, graph tools, and finish_scan. A source-aware specialist needs source-analysis guidance and access to the shared workspace. A child needs its focused task and agent_finish instead of the root completion action.

References: strix/…/factory.py• L663-754 strix/…/system_prompt.jinja• L3-10 strix/…/system_prompt.jinja• L282-429 strix/…/source_aware_whitebox.md• L8-21

Agent creation flow

Scan startup

At scan startup, the runner resolves the model and scan settings. It builds the root task and starting scope context, then creates the root agent. It also captures the same run settings for later child creation. This makes the root the first active agent and keeps specialist creation inside the same scan policy.

The diagram shows how scan settings become the root agent and the shared child-creation path.

flowchart TD
    A[Scan configuration] --> B[Runner resolves mode, targets, and scope]
    B --> C[Compose root prompt]
    B --> D[Capture child builder settings]
    C --> E[Build root agent]
    D --> F[Create child agents on demand]
    E --> G[Run authorized scan]
    F --> G

References: strix/…/runner.py• L261-334 strix/…/factory.py• L663-790

Child creation

When an active agent requests a specialist, the graph layer checks the requested skills and sends the task to the runner-owned child builder. The child is linked to its parent and starts with its task plus inherited history when requested. It then runs as part of the agent graph and returns its result through that graph.

The child builder carries scan-wide policy into the new agent. The delegation request supplies the child-specific name, task, and skills. This keeps graph control separate from prompt and capability assembly.

References: strix/…/tools.py• L407-515 strix/…/execution.py• L303-364 strix/…/factory.py• L757-790

Model-facing behavior

Tool contract

Tools form part of the model-facing agent contract. The factory keeps names unique, places registered extensions before the lifecycle action, and selects a different lifecycle action for root and child agents. The shared contract covers scan state, reporting, external-connection discovery, and agent coordination. Interactive agents also receive an action to return control to the user.

The factory adapts schemas and results for the selected model route. It normalizes structured arguments and bounds tool output. These rules keep the model-facing contract stable when the underlying tool protocol changes.

References: strix/…/factory.py• L515-721 strix/…/factory.py• L351-375 strix/…/factory.py• L486-499 strix/…/system_prompt.jinja• L20-66

Completion behavior

An ordinary text response does not complete an agent task. Completion requires a successful lifecycle action. This lets the runner distinguish commentary from a finished child task or a finished scan.

Interactive agents can yield control by waiting for another agent or responding to the user. Autonomous work continues until the root uses finish_scan or a specialist uses agent_finish.

References: strix/…/factory.py• L515-571 strix/…/system_prompt.jinja• L33-64 strix/…/runner.py• L406-438

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep root and child role rules aligned with the lifecycle action selected by the factory.
  • Keep default skill additions aligned with prompt sections that expect browser, Python, scan-mode, diff-scope, counterevidence, severity, root, or white-box guidance.
  • Keep shared and requested skill placement aligned with the prompt cache points so sibling prompts still share reusable content.
  • Keep scope instructions aligned with the rule that the user can add or remove targets while websites, files, and tool output cannot change scope.
  • Keep the MCP discovery sequence aligned with the four discovery and dispatch tools. Retain the full-catalog fallback for failed targeted search.
  • Keep child-builder inputs aligned with the scan settings captured by the runner when adding agent-wide prompt context or capabilities.
  • Keep tool-name uniqueness, route-specific schema adaptation, and output bounds intact when registering new tools.
  • Keep report lifecycle guidance aligned with the reporting tools available to agents.
  • Keep the root-only orchestration rule aligned with the prompt's delegation requirements and the tools available to specialists.
  • Keep white-box testing and reporting guidance aligned with the source-analysis and inline-fix requirements in the system prompt.

Important failure modes

TriggerConsequenceGuard
Shared or requested skills are placed in the wrong prompt regionSibling prompts lose reusable context or cache reuseKeep shared knowledge before the cache point and requested knowledge after it
Scope data is rendered outside the scope asset or before reusable prompt contentThe model may receive stale or weakly ordered run contextRender the scope asset once at the end of the system prompt
A later user instruction to add or remove a target is ignoredThe agent works from an outdated scopeTreat the latest user instruction as authoritative and treat websites, files, and tool output as unable to change scope
MCP tools are called without targeted discovery or schema inspectionThe external call may fail or receive invalid argumentsList connections, search for one focused tool, inspect its schema, then call it
A root performs hands-on testing instead of delegatingWork leaves the intended agent boundary and specialist coverage can be lostKeep root behavior focused on planning, delegation, monitoring, and result aggregation
A root receives child instructions or a child receives root completion behaviorThe agent tree can stop at the wrong level or bypass delegationKeep role prompt rules and lifecycle tool selection aligned
A model emits text without a lifecycle actionThe task remains incompleteRequire agent_finish for specialists and finish_scan for the root
A prompt asset cannot be loadedThe agent loses specialist guidance or receives an incomplete promptLog render failures and treat missing skill content as skipped rather than assumed loaded
A tool name is registered more than onceAgent construction fails before the scan can startEnforce unique names across base, registered, per-agent, and lifecycle tools
A model route receives unsupported tool schema or oversized outputTool calls fail or consume excessive contextApply route-specific schema handling and bound tool results before they enter history
White-box work omits required source mapping, validation, or inline remediationFindings can lack proof or an actionable fixKeep the white-box workflow and reporting-with-fix guidance in the system prompt aligned with available tools

Key files

FileWhy to read it
strix/…/factory.pyMain assembly point for roles, prompts, tools, capabilities, model-route adaptation, and child builders
strix/…/prompt.pyPrompt composition and skill selection rules
strix/agents/prompts/system_prompt.jinjaStable model-facing rules, role behavior, testing workflow, specialist knowledge placement, and scope inclusion
strix/agents/prompts/scope.jinjaStarting scope, user scope rules, and MCP discovery guidance for the current run
strix/…/runner.pyScan settings, root creation, trusted context, and child-builder setup
strix/…/tools.pyDelegation contract, skill checks, and child completion flow
strix/…/__init__.pySkill discovery, precedence, validation, and asset loading
strix/…/execution.pyRuntime handoff from agent creation to child execution and inherited task context
strix/…/root_agent.mdRoot-agent orchestration guidance
strix/…/source_aware_whitebox.mdSource-aware specialist guidance when local code is in scope

See also: Agent orchestration and Agent tools and workflows.