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
| Trigger | Consequence | Guard |
|---|---|---|
| Shared or requested skills are placed in the wrong prompt region | Sibling prompts lose reusable context or cache reuse | Keep shared knowledge before the cache point and requested knowledge after it |
| Scope data is rendered outside the scope asset or before reusable prompt content | The model may receive stale or weakly ordered run context | Render the scope asset once at the end of the system prompt |
| A later user instruction to add or remove a target is ignored | The agent works from an outdated scope | Treat 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 inspection | The external call may fail or receive invalid arguments | List connections, search for one focused tool, inspect its schema, then call it |
| A root performs hands-on testing instead of delegating | Work leaves the intended agent boundary and specialist coverage can be lost | Keep root behavior focused on planning, delegation, monitoring, and result aggregation |
| A root receives child instructions or a child receives root completion behavior | The agent tree can stop at the wrong level or bypass delegation | Keep role prompt rules and lifecycle tool selection aligned |
| A model emits text without a lifecycle action | The task remains incomplete | Require agent_finish for specialists and finish_scan for the root |
| A prompt asset cannot be loaded | The agent loses specialist guidance or receives an incomplete prompt | Log render failures and treat missing skill content as skipped rather than assumed loaded |
| A tool name is registered more than once | Agent construction fails before the scan can start | Enforce unique names across base, registered, per-agent, and lifecycle tools |
| A model route receives unsupported tool schema or oversized output | Tool calls fail or consume excessive context | Apply route-specific schema handling and bound tool results before they enter history |
| White-box work omits required source mapping, validation, or inline remediation | Findings can lack proof or an actionable fix | Keep the white-box workflow and reporting-with-fix guidance in the system prompt aligned with available tools |
Key files
| File | Why to read it |
|---|---|
| strix/…/factory.py | Main assembly point for roles, prompts, tools, capabilities, model-route adaptation, and child builders |
| strix/…/prompt.py | Prompt composition and skill selection rules |
strix/agents/prompts/system_prompt.jinja | Stable model-facing rules, role behavior, testing workflow, specialist knowledge placement, and scope inclusion |
strix/agents/prompts/scope.jinja | Starting scope, user scope rules, and MCP discovery guidance for the current run |
| strix/…/runner.py | Scan settings, root creation, trusted context, and child-builder setup |
| strix/…/tools.py | Delegation contract, skill checks, and child completion flow |
| strix/…/__init__.py | Skill discovery, precedence, validation, and asset loading |
| strix/…/execution.py | Runtime handoff from agent creation to child execution and inherited task context |
| strix/…/root_agent.md | Root-agent orchestration guidance |
| strix/…/source_aware_whitebox.md | Source-aware specialist guidance when local code is in scope |
See also: Agent orchestration and Agent tools and workflows.