Chapter 2: Building your first AI agent
This chapter introduces the construction of a controlled, inspectable AI agent by contrasting it with scripts and framing agent execution as a component-based decision loop.
After this chapter you will be able to
- Controlled agent decision loop. Explain how wrapping an LLM with explicit messages, tools, and artifacts turns reactive text generation into a controlled decision-making loop that can be inspected, replayed, and defended.
- Script automation limitations. Explain why conventional security scripts and one-off automation require humans as the primary decision-makers and can become unreliable when their expected environment changes.
- Standalone LLM limitations. Describe what an LLM can contribute to dynamic security analysis and why a prompt-driven chatbot alone is inadequate for accountable security decisions.
- Agent feedback loop. Describe an agent as a system that receives input, decides what to do, invokes an action, observes the result, records what happened, and repeats this controlled cycle toward a goal.
- Scripts, LLMs, and agents. Distinguish a procedural script and a standalone LLM from an agent. Explain that scripts follow fixed step-by-step instructions, while an LLM generates text for a prompt without persistent memory or direct action capabilities, whereas an agent uses an LLM as a brain plus memory, tools, planning, environmental interaction, and actions.
- Adaptive security workflow rationale. Explain why offensive-security workflows need agentic reasoning: reconnaissance feeds triage, triage feeds prioritization, and failures require reassessment rather than a linear fixed path. Describe how agents help handle high volumes of collected data by identifying where people should focus.
- Five-component agent loop. Describe an agent as a structured loop that iterates through reasoning, action, observation, reflection, and recording, and explain that connecting these components enables complex task performance.
- Five-component agent architecture. Describe the five core components of an AI agent: messages, tools, memory, an agent controller, and artifacts. Explain that together they support an agent workflow rather than a one-off model response.
- Tool-enabled external interaction. Explain that tools are custom functions, API calls, or database queries an agent can invoke when reasoning alone is insufficient. Describe how tools let an agent retrieve current external information or perform specialized operations such as reliable calculations.
- Controller reasoning loop. Trace the agent controller's reasoning loop: understand the request, determine needed information or actions, call appropriate tools, synthesize the results, and respond. Explain that the controller orchestrates and coordinates the other components to fulfill the request.
- Persistent memory and artifacts. Describe memory as retained information across interactions, including short-term conversational context and long-term facts stored in a vector database. Distinguish memory from artifacts, which are tangible model outputs such as documents, code files, reports, or charts that can be saved, downloaded, edited, or passed on.
- ReAct reasoning-action loop. Describe the ReAct loop as an iterative cycle in which an LLM reasons about a plan, acts on the outside world, and observes the results until the user's problem is solved.
- ReAct practical value. Explain why the ReAct loop is useful: reasoning grounds actions in reality and helps prevent hallucinations, observation lets the agent adapt its plan to discoveries, and the decision process is transparent to the user.
- Agent accountability and observability. Explain why a standalone LLM is insufficient for high-stakes cybersecurity decisions and how an agent makes its behavior observable and accountable. Describe how messages, tools, memory, and artifacts allow reasoning steps, decisions, actions, and results to be recorded and inspected.
- Bounded agent responsibility. Describe the kinds of bounded security tasks suited to an individual agent, such as reconnaissance, triage, or analysis. Explain that an agent is not an autonomous free-for-all, a replacement for tools or scripts, or a source of new capabilities; it coordinates existing capabilities through controlled reasoning, explicit actions, and recorded outcomes.
- Minimal agent API contract. Explain the minimal agent specification as the smallest set of interfaces and data structures an agent must support. Describe how explicit messages, tool invocations, observations, and recorded artifacts define what an agent does and records.
- Framework-independent portability. Describe why the specification is deliberately framework-agnostic: an AI library can be swapped without breaking the surrounding workflow because the contract specifies required behavior and records, not framework implementation details.
- Five-step agent workflow. Trace the minimal agent's five actions in order: decide which tool to run, execute the first tool, record its result as an artifact, pass that artifact to a second tool, and stop.
- Minimal agent workflow. Describe the minimal agent's workflow: it takes a small local text input, uses one tool to extract URLs, uses a second tool to summarize those URLs, and controls the order of execution.
- Agent message roles. Describe the four standard message roles—System, User, Agent, and Tool—and explain what each contributes to an agent conversation.
- Message and observation records. Explain what the Message and Observations classes record, including Message role, content, timestamp, and metadata, and observation details about an action such as tool name, model inputs and outputs, errors, and monitoring information.
- Agent tool interfaces. Explain that tools let an agent interact with the world, including custom functions such as regex parsers and calls to external-service APIs such as vulnerability scanners.
- Shared tool data schema. Describe why tool inputs and outputs must follow the Observations schema: using the same format makes data movement traceable across agent modules.
- URL extraction tool responsibility. Describe the ExtractUrlsTool as a tool that scans input text and returns items that look like URLs, while inheriting its invocation method from the base Tool class.
- Tool context-free scope. Explain that the URL extraction tool performs one task only: it has no awareness of execution context and neither decides when it runs nor determines how its output is used.
- Artifact-consuming summarization tool. Describe how the second tool consumes the artifact from the URL-extraction tool and generates a short summary.
- Artifact logging format. Describe how the agent records artifacts by saving model outputs as JSONL, with one JSON object per line, in a log file under run_dir. Explain that each new trace is appended as a new line rather than replacing prior traces.
- Audit trail value. Explain why artifact logging is necessary for security-agent work: it provides an audit trail that can show exactly what the agent did, supports assessments and debugging, and demonstrates adherence to the authorized testing scope for compliance and legal protection.
- Minimal agent loop. Describe the minimal agent loop as an agent deciding execution order, invoking its URL-extraction and URL-summary tools, observing results, and recording outcomes.
- Minimal agent assembly. Describe how the runnable minimal agent combines a minimal agent model, its two tools, and an ArtifactLogger that captures artifacts produced by the model.
- Interoperable agent foundation. Explain that the small set of minimal-agent rules provides the foundational layer for interoperable agents, while framework abstractions, orchestration, and memory stores are additional layers built on top.
- Bounded agent autonomy. Explain why an agent that can reason, act, and reflect autonomously is both useful and dangerous, and why offensive-security automation must operate within clearly defined boundaries.
- Safety governance controls. Describe the technical controls this section introduces—safety gates, sandboxing, logging, and auditability—and state that they turn Chapter 1's ethical ideas into enforceable engineering practices.
- Dual-use authorization boundary. Explain why offensive-security capabilities are dual-use and why authorization and intent distinguish legitimate penetration testing from criminal activity. State that strict governance is necessary to keep agent activity within ethical and legal boundaries.
- Automation-amplified operational risks. Describe how an AI agent's automated reasoning can amplify offensive-security risk through scope mistakes, misunderstood network boundaries, or destructive commands. Give examples of harmful outcomes or unsafe actions identified in the section.
- Governance as circuit breaker. Explain that governance mechanisms are circuit breakers between agent creativity and real-world consequences: they limit execution until verification occurs. State why auditable logging and human approval demonstrate integrity rather than serving as unnecessary bureaucracy.
- Safety gate purpose. Explain that a safety gate is a checkpoint that enforces review or specified conditions before an agent step is allowed to continue, and distinguish manual gates from automated ones.
- Critical target blocking. Describe the simple gate's target checks: it automatically blocks actions whose target contains "prod", "payment", or "core-db", while nonmatching targets require explicit operator approval before execution.
- Sandboxing as final defense. Explain sandboxing as running agent-generated code in an isolated environment that restricts access to the broader system. Describe why it remains necessary even after safety gates and human approval: agents may execute unreviewed code with dangerous unintended side effects.
- Replayable agent accountability. Explain why an AI agent must log what it decided, why it chose an action, when the action occurred, and whether it succeeded or failed. Describe how expanding the ArtifactLogger schema with metadata makes actions reconstructable, supports replay and accountability, and helps demonstrate that authorized bounds were respected.
- Pre-engagement operational policies. State the operational policies that must be written down before an engagement: authorized scope, human approval, data minimization, artifact deletion, and responsible disclosure.
- Authorized scope and approval. Describe how authorized scope limits an agent to written targets, time windows, and prohibited actions, and explain that every run requires at least one human approval gate.
- Global kill switch design. Describe how the global kill switch provides an immediate manual abort for all agent operations. Explain that agents check a shared active flag, and that setting active=True signals an emergency stop.
- Safety and governance safeguards. Describe how safety gates, sandboxing, comprehensive logging, operational policies, and kill switches collectively govern an automated agent. Explain the distinct protective role of each safeguard.
- Triage agent purpose. Describe the triage agent as an agent that reads reconnaissance data, reasons about which findings matter, and produces a ranked summary while remaining within ethical boundaries.
- Post-recon triage purpose. Explain that triage addresses the attention bottleneck after reconnaissance, when large amounts of scan output contain mostly noise but may hide a few important details.
- Triage agent boundaries. Describe the triage agent as a post-recon assistant that works only on saved output files and helps decide where to focus first; it does not scan, probe, or exploit network resources.
- Reconnaissance output signal. Explain why typical nmap service-discovery output becomes difficult to review as scope grows, and identify the kinds of details that can be buried in repetitive results.
- Narrow triage decision. Describe the agent's narrow task as treating nmap output as a document and identifying hosts or services that stand out enough to justify further investigation, without scanning, exploiting, or assuming later actions.
- Triage agent mission. Explain that the triage agent is not expected to find vulnerabilities; its practical role is to reduce reconnaissance noise and surface useful signals so a human can make faster, more consistent decisions.
- Reconnaissance signal categories. Describe the signals the agent uses for triage: unusual exposed services or ports, unexpected service combinations, groups of hosts with matching service stacks, and red flags such as legacy, end-of-life, or improperly internet-facing services.
- Prioritized triage summary. Describe a prioritized triage summary as the agent’s concise output for quick human review, derived from reconnaissance data and focused on the most promising hosts or services.
- Explainable triage decisions. Explain that each flagged item includes a brief reason for the flag, preserving the agent’s reasoning so a human can agree, disagree, investigate further, or revisit the decision later.
- Recon triage bottleneck. Explain why recon triage, rather than scanning tooling, is often the bottleneck for bug hunters and how the agent shortens the path from completed scans to targets worth testing.
- Consistent explainable triage. Describe how the agent conducts a repeatable first-pass triage by flagging anomalies, grouping similar hosts, and surfacing outliers, while recording decisions and explanations for its flags.
- Constrained human-centered automation. Explain the safety boundaries of the workflow: the agent analyzes only already-collected data, never touches the network, expands scope, or probes targets, and produces inspectable artifacts while leaving judgment and reversible decisions to the human.
What it builds on
- Introducing AI Agents: Reasoning That Acts (chapter 1) · The introduction assumes the prior framing of AI agents as reasoning systems that act.
- Pipelines: Information Routing Systems (chapter 1) · The introduction assumes that pipelines organize controlled offensive-security workflows.
- Intelligence as a Component (chapter 1) · The use of LLM intelligence as a component of a security system.
- What Is An AI Agent? (chapter 1) · The earlier definition of an AI agent.
- Artifacts provide precise decision-making in offensive security (chapter 1) · Artifacts as the units that support precise decision-making in offensive-security systems.
- Traditional offensive security workflows (chapter 1) · Traditional offensive-security workflows and their use of tools and automation.
- Large language models (LLMs) as security tools (chapter 1) · LLMs as security tools and their role in security workflows.
- Pipelines as the Organizing Principle (chapter 1) · Pipelines as systems that route information between stages.
Section by section
Introduction
This chapter introduces the construction of a controlled, inspectable AI agent by contrasting it with scripts and framing agent execution as a component-based decision loop.
- Chapter construction roadmap: Describe the chapter’s progression from distinguishing agents from scripts and tools, through building a minimal Python agent, to applying governance patterns and recon-data triage.
Why it matters: This roadmap helps you connect the minimal implementation to the safety and practical workflow topics that follow. - Controlled agent decision loop: Explain how wrapping an LLM with explicit messages, tools, and artifacts turns reactive text generation into a controlled decision-making loop that can be inspected, replayed, and defended.
Why it matters: The chapter’s central design goal is to make LLM-driven decisions controllable and accountable rather than opaque text generation. - Minimal agent construction scope: State that the chapter builds a real agent from the ground up as an illustrative minimal implementation, rather than a clever demo or a production system, using Python without AI frameworks before considering frameworks such as LangChain and AutoGen.
Why it matters: Understanding the intentionally small scope keeps the focus on explicit agent structure rather than framework complexity or production claims.
Key terms: script-based automation, agents, scripts, tools, minimal agent specification, recon data triage, large language model, messages, artifacts, controlled decision-making loop
2.1 Limitations of script-based automation
This section contrasts brittle script automation and insufficient standalone LLM chatbots to motivate agents that can make accountable decisions in changing security environments.
- Script automation limitations: Explain why conventional security scripts and one-off automation require humans as the primary decision-makers and can become unreliable when their expected environment changes.
Why it matters: Recognizing where scripts break down clarifies why security workflows need more than predefined instructions. - Standalone LLM limitations: Describe what an LLM can contribute to dynamic security analysis and why a prompt-driven chatbot alone is inadequate for accountable security decisions.
Why it matters: An LLM can provide useful reasoning, but security work needs state, environmental responsiveness, and explainable decisions rather than unstructured prompt responses.
Key terms: scripts, cron jobs, one-off tools, predefined instructions, fixed file state, artifacts, large language models (LLMs), scan output, anomalies, next steps
2.2 What is an agent?
This section defines AI agents, distinguishes them from scripts and standalone LLMs, and explains why their controlled feedback loops suit dynamic offensive-security work.
- Agent feedback loop: Describe an agent as a system that receives input, decides what to do, invokes an action, observes the result, records what happened, and repeats this controlled cycle toward a goal.
Why it matters: The feedback loop lets an agent adapt its next step to results rather than blindly following a fixed sequence. - Scripts, LLMs, and agents: Distinguish a procedural script and a standalone LLM from an agent. Explain that scripts follow fixed step-by-step instructions, while an LLM generates text for a prompt without persistent memory or direct action capabilities, whereas an agent uses an LLM as a brain plus memory, tools, planning, environmental interaction, and actions.
Why it matters: This distinction helps you choose an adaptive agent when a fixed script or a single model response cannot handle the work. - Adaptive security workflow rationale: Explain why offensive-security workflows need agentic reasoning: reconnaissance feeds triage, triage feeds prioritization, and failures require reassessment rather than a linear fixed path. Describe how agents help handle high volumes of collected data by identifying where people should focus.
Why it matters: Security engagements produce more endpoints, parameters, headers, and responses than a human can efficiently prioritize without adaptive assistance. - Human control and auditability: Explain that agents augment rather than replace human judgment, and that safe agent operation requires control gates for human intervention plus records of actions, tools used, steps taken, and observed responses so work can be reviewed, replayed, and defended.
Why it matters: Human controls and an auditable record make autonomous security work safer and accountable when conditions or outcomes go wrong.
Key terms: agent, controlled decisions, perceive → reason → act → observe, feedback loop, autonomous task execution, script, procedural programming, LLM, text-prediction engine, memory
2.3 Anatomy of an agent
This section introduces an agent as an iterative structured loop connecting reasoning, action, observation, reflection, and recording.
- Five-component agent loop: Describe an agent as a structured loop that iterates through reasoning, action, observation, reflection, and recording, and explain that connecting these components enables complex task performance.
Why it matters: This loop is the basic model for understanding how an agent can do work that would otherwise require human effort.
Key terms: structured loop, reasoning, action, observation, reflection, recording
2.3.1 Core components
This section explains the five components of an AI agent and how they combine to reason over requests, use external capabilities, retain context, and produce usable outputs.
- Five-component agent architecture: Describe the five core components of an AI agent: messages, tools, memory, an agent controller, and artifacts. Explain that together they support an agent workflow rather than a one-off model response.
Why it matters: Naming the components lets you understand what an agent needs to turn model output into a usable workflow. - Messages and chain-of-thought reasoning: Explain that messages are structured communications which agents combine into prompts, often using multiple messages rather than a single chatbot turn. Describe Chain of Thought as breaking a complex problem into intermediate steps to improve result accuracy.
Why it matters: Structured messages and stepwise reasoning give an agent the context and decomposition needed for more reliable responses. - Tool-enabled external interaction: Explain that tools are custom functions, API calls, or database queries an agent can invoke when reasoning alone is insufficient. Describe how tools let an agent retrieve current external information or perform specialized operations such as reliable calculations.
Why it matters: Tools are what let an agent act beyond its training knowledge and use specialized capabilities to complete a task. - Controller reasoning loop: Trace the agent controller's reasoning loop: understand the request, determine needed information or actions, call appropriate tools, synthesize the results, and respond. Explain that the controller orchestrates and coordinates the other components to fulfill the request.
Why it matters: The controller makes the system an agent by deciding how messages, memory, tools, and results should be used for a task. - Persistent memory and artifacts: Describe memory as retained information across interactions, including short-term conversational context and long-term facts stored in a vector database. Distinguish memory from artifacts, which are tangible model outputs such as documents, code files, reports, or charts that can be saved, downloaded, edited, or passed on.
Why it matters: Memory preserves relevant context, while artifacts make an agent's work persistent and usable by people or other LLMs.
Key terms: messages, tools, memory, agent controllers, artifacts, prompt, Chain of Thought (CoT), reasoning, custom functions, API calls
2.3.2 The ReAct agent loop
This section explains the iterative ReAct framework through which an agent reasons, acts, observes results, and can reflect and record information to improve transparent decision-making.
- ReAct reasoning-action loop: Describe the ReAct loop as an iterative cycle in which an LLM reasons about a plan, acts on the outside world, and observes the results until the user's problem is solved.
Why it matters: This loop is the basic mechanism that lets an LLM make decisions, use tools, and revise its next step from real results. - Reflection and recording extensions: Explain the two additions to the original ReAct loop: reflection evaluates the model's own performance to inform next steps, while recording stores session information, context, learnings, logs, and outputs for future reference and decisions.
Why it matters: Reflection and recording extend the basic loop with self-evaluation and retained information that can improve later decisions. - ReAct practical value: Explain why the ReAct loop is useful: reasoning grounds actions in reality and helps prevent hallucinations, observation lets the agent adapt its plan to discoveries, and the decision process is transparent to the user.
Why it matters: These properties make autonomous tool use more adaptable and understandable than an ungrounded model response.
Key terms: ReAct, Reasoning, Action, Observation, LLM, Reflection, Recording, logs, context, hallucinations
2.3.3 The scope and responsibility of an agent
This section explains that agents add observable, controlled, accountable structure around LLM reasoning for bounded security work rather than replacing existing tools or operating without limits.
- Agent accountability and observability: Explain why a standalone LLM is insufficient for high-stakes cybersecurity decisions and how an agent makes its behavior observable and accountable. Describe how messages, tools, memory, and artifacts allow reasoning steps, decisions, actions, and results to be recorded and inspected.
Why it matters: Observable reasoning lets security teams inspect, refine, and control AI-assisted decisions with appropriate human intervention. - Telemetry-based decision tracing: Describe how telemetry and artifacts log an agent's decisions, actions, and results, and state that tools such as LangSmith can manage LLM logs, metrics, traces, and events for debugging and auditing.
Why it matters: Traces and logs give teams evidence to debug agent behavior and audit what happened during security work. - Bounded agent responsibility: Describe the kinds of bounded security tasks suited to an individual agent, such as reconnaissance, triage, or analysis. Explain that an agent is not an autonomous free-for-all, a replacement for tools or scripts, or a source of new capabilities; it coordinates existing capabilities through controlled reasoning, explicit actions, and recorded outcomes.
Why it matters: Limiting an agent's responsibility makes security automation more understandable, governable, and safer to operate. - Artifacts between agent stages: Explain why artifacts become more important as systems grow more complex: when agents are chained together, artifacts serve as the interface between stages.
Why it matters: Stable artifacts let separate stages exchange recorded outputs instead of relying on hidden or ambiguous handoffs.
Key terms: LLM, agent, messages, tools, memory, artifacts, telemetry tools, LangSmith, logs, metrics
2.4 The minimal agent specification
Defines a framework-agnostic API contract for the smallest portable, testable, and auditable agent implementation.
- Minimal agent API contract: Explain the minimal agent specification as the smallest set of interfaces and data structures an agent must support. Describe how explicit messages, tool invocations, observations, and recorded artifacts define what an agent does and records.
Why it matters: A clear contract makes an agent's behavior inspectable and consistent rather than hidden inside implementation details. - Framework-independent portability: Describe why the specification is deliberately framework-agnostic: an AI library can be swapped without breaking the surrounding workflow because the contract specifies required behavior and records, not framework implementation details.
Why it matters: Framework independence lets workflows remain usable and comparable even as underlying AI libraries change. - Deliberate minimal implementation: State that the specification prioritizes portability and auditability over feature completeness. Describe the next implementation as a clarity-focused minimal agent with exactly two tools, one artifact passed between them, and a stop condition rather than memory, optimization, or framework-specific abstractions.
Why it matters: Keeping the first implementation intentionally small makes its control flow and recorded decisions easy to understand and verify.
Key terms: minimal agent specification, API contract, messages, tool invocations, observations, artifacts, framework-agnostic, portability, surrounding workflows, auditability
2.5 Building the minimal agent
Introduces the smallest concrete agent implementation as a five-step, constrained workflow that makes agent mechanics explicit.
- Minimal agent constraints: Describe the deliberately limited capabilities of the minimal agent: it has no memory, optimization, or network access, so its mechanics can be seen clearly.
Why it matters: Constraining the example makes it easier to identify the essential structure of an agent before adding more capabilities. - Five-step agent workflow: Trace the minimal agent's five actions in order: decide which tool to run, execute the first tool, record its result as an artifact, pass that artifact to a second tool, and stop.
Why it matters: This small sequence is the foundational execution pattern that later agents elaborate. - Foundational implementation purpose: Explain that this implementation is intended to be the smallest example satisfying the earlier agent model, and that understanding its structure prepares the reader to understand the other agents in the book.
Why it matters: The example supplies a reusable mental model for recognizing the same structure in more capable agents.
Key terms: memory, optimization, network access, mechanics of agency, tool, artifact, decide, execute, stop, agent model
2.5.1 What this agent does
This subsection defines a minimal local agent that extracts URLs, summarizes them, and records its ordered steps as an artifact.
- Minimal agent workflow: Describe the minimal agent's workflow: it takes a small local text input, uses one tool to extract URLs, uses a second tool to summarize those URLs, and controls the order of execution.
Why it matters: This shows how an agent coordinates tools into a small, traceable task rather than merely running an isolated script. - Summary artifact and step record: Explain that the agent produces a short summary artifact and records each execution step, so its output and actions are captured rather than left implicit.
Why it matters: Recorded artifacts make the agent's result and its execution trail available for inspection. - Local deterministic processing: State that all input is local and deterministic and that the minimal agent makes no live network calls.
Why it matters: Keeping this example local and deterministic makes its behavior bounded and repeatable while introducing the agent pattern.
Key terms: Tool A, Tool B, execution order, URL extraction, URL summarization, summary artifact, records each step, artifact, local, deterministic
2.5.2 Messages and observations
This subsection defines the conversational message roles an agent uses and the Message and Observation records needed to preserve agent activity for monitoring and tracing.
- Agent message roles: Describe the four standard message roles—System, User, Agent, and Tool—and explain what each contributes to an agent conversation.
Why it matters: Separating messages by role lets the agent distinguish instructions, human requests, its own responses, and tool results. - Message and observation records: Explain what the Message and Observations classes record, including Message role, content, timestamp, and metadata, and observation details about an action such as tool name, model inputs and outputs, errors, and monitoring information.
Why it matters: These records make an agent's inputs, actions, results, and failures available for monitoring and error tracing. - JSON-compatible artifact data: State why artifacts should use JSON-compatible basic types—strings, numbers, booleans, arrays, and objects—and describe converting complex values such as NumPy arrays to lists and Python objects to dictionaries.
Why it matters: JSON-compatible records can be readily stored and visualized in logs, dashboards, and other data views.
Key terms: System, User, Agent, Tool, message role, Message, Observations, role, content, timestamp
2.5.3 Tools
This subsection defines tools as an agent's interface to the world and specifies a common schema for invoking and tracing them.
- Agent tool interfaces: Explain that tools let an agent interact with the world, including custom functions such as regex parsers and calls to external-service APIs such as vulnerability scanners.
Why it matters: Tools give an agent a controlled way to perform work beyond its internal reasoning. - Shared tool data schema: Describe why tool inputs and outputs must follow the Observations schema: using the same format makes data movement traceable across agent modules.
Why it matters: A shared schema lets you follow data as it passes through an agent rather than losing its origin or meaning. - Base Tools schema: Describe the base Tools schema as defining tool metadata—its name and description—and an .invoke() method that runs a function, invokes an API, or performs another task.
Why it matters: The common tool interface makes different kinds of executable capabilities usable in a uniform way.
Key terms: tools, custom function, API call, regex parser, vulnerability scanner, Observations class, input and output data formats, schema, agent modules, trace the movement of data
2.5.4 Tool A: extract URLs
This subsection defines a simple URL-extraction tool and clarifies its deliberately narrow, context-free responsibility.
- URL extraction tool responsibility: Describe the ExtractUrlsTool as a tool that scans input text and returns items that look like URLs, while inheriting its invocation method from the base Tool class.
Why it matters: A narrowly defined tool gives the agent a reliable capability without embedding agent-level decision-making in the tool. - Tool context-free scope: Explain that the URL extraction tool performs one task only: it has no awareness of execution context and neither decides when it runs nor determines how its output is used.
Why it matters: Keeping decisions outside a single-purpose tool makes the agent's behavior easier to control, inspect, and compose.
Key terms: ExtractUrlsTool, Tool, invocation method, URL, execution context, single task
2.5.5 Tool B: summarize URLs
This subsection introduces a URL-summarization tool that transforms the prior tool’s artifact into a short structured summary while remaining independent of pipeline context.
- Artifact-consuming summarization tool: Describe how the second tool consumes the artifact from the URL-extraction tool and generates a short summary.
Why it matters: This shows how one focused tool can turn an earlier result into a useful next-stage artifact. - Tool interface independence: Explain that the summarization tool uses structured input and structured output without needing knowledge of the pipeline behavior before or after it.
Why it matters: Independent tool interfaces make pipeline components easier to connect and reason about.
Key terms: SummarizeUrlsTool, artifact, short summary, structured input, structured output, upstream behavior, downstream behavior
2.5.6 Artifacts and logging
This subsection defines agent outputs as artifacts and explains logging them as JSONL to create an auditable record of each run.
- Artifact logging format: Describe how the agent records artifacts by saving model outputs as JSONL, with one JSON object per line, in a log file under run_dir. Explain that each new trace is appended as a new line rather than replacing prior traces.
Why it matters: A consistent append-only artifact log preserves the record of an agent's activity across a run. - Audit trail value: Explain why artifact logging is necessary for security-agent work: it provides an audit trail that can show exactly what the agent did, supports assessments and debugging, and demonstrates adherence to the authorized testing scope for compliance and legal protection.
Why it matters: A defensible security workflow needs evidence of both the agent's actions and its compliance with the engagement scope.
Key terms: artifacts, JSONL, artifact logger, run_dir, traces, model outputs, audit trail, assessments, debugging, compliance
2.5.7 The minimal agent loop
Defines the minimal agent loop as explicit tool-order decisions, actions, observations, and recorded outcomes.
- Minimal agent loop: Describe the minimal agent loop as an agent deciding execution order, invoking its URL-extraction and URL-summary tools, observing results, and recording outcomes.
Why it matters: This makes the agent's behavior inspectable because its decisions and results are explicit. - Explicit loop behavior: Explain that the minimal loop contains only explicit decisions, actions, observations, and recorded outcomes, without callbacks, implicit state, or framework-managed behavior.
Why it matters: Keeping the loop explicit lets a practitioner see exactly how the agent acted and what happened.
Key terms: minimal agent loop, execution order, actions, observations, recorded outcomes, MinimalAgent, callbacks, implicit state, framework-managed behavior, explicit decisions
2.5.8 Putting it together
This subsection runs the minimal agent with its two tools and artifact logging, emphasizing that these simple components form the base layer for interoperable agents.
- Minimal agent assembly: Describe how the runnable minimal agent combines a minimal agent model, its two tools, and an ArtifactLogger that captures artifacts produced by the model.
Why it matters: This is the smallest concrete setup that turns the earlier agent components into an executable agent. - Interoperable agent foundation: Explain that the small set of minimal-agent rules provides the foundational layer for interoperable agents, while framework abstractions, orchestration, and memory stores are additional layers built on top.
Why it matters: Keeping the foundation small makes it easier to understand what later agent frameworks and coordination features are adding. - Harmless tool exercise: Apply the exercise by describing a simple Tool subclass that performs a harmless text operation and logs its input and output with ArtifactLogger.
Why it matters: Writing and logging one safe tool demonstrates a substantial portion of the working-agent pattern without introducing risky behavior.
Key terms: ArtifactLogger, artifacts, minimal agent model, tools, interoperable agents, framework abstractions, orchestration, memory stores, Tool subclass, input
2.6 Safety and governance
Introduces safety and governance as technical controls that bound autonomous offensive-security agents and make them trustworthy.
- Bounded agent autonomy: Explain why an agent that can reason, act, and reflect autonomously is both useful and dangerous, and why offensive-security automation must operate within clearly defined boundaries.
Why it matters: Autonomy creates value only when the agent is prevented from acting outside authorized limits. - Safety governance controls: Describe the technical controls this section introduces—safety gates, sandboxing, logging, and auditability—and state that they turn Chapter 1's ethical ideas into enforceable engineering practices.
Why it matters: Concrete controls make safety expectations operational rather than leaving them as intentions. - Trustworthy systems rationale: Explain that safety and governance controls are established engineering principles rather than bureaucratic overhead, because they transform clever scripts into trustworthy systems.
Why it matters: Treating governance as engineering helps teams build systems that can be trusted in real security operations.
Key terms: autonomy, clearly defined boundaries, offensive security automation, safety gates, sandboxing, logging, auditability, technical controls, engineering principles, trustworthy systems
2.6.1 Why safety matters
This section explains why AI offensive-security agents require strict governance, authorization, guardrails, logging, and human approval to prevent harmful, unlawful, or out-of-scope actions.
- Dual-use authorization boundary: Explain why offensive-security capabilities are dual-use and why authorization and intent distinguish legitimate penetration testing from criminal activity. State that strict governance is necessary to keep agent activity within ethical and legal boundaries.
Why it matters: An agent performing technically valid actions can still cause legal and ethical harm if it acts without authorization or outside the agreed scope. - Automation-amplified operational risks: Describe how an AI agent's automated reasoning can amplify offensive-security risk through scope mistakes, misunderstood network boundaries, or destructive commands. Give examples of harmful outcomes or unsafe actions identified in the section.
Why it matters: Automation can turn a misunderstanding or scope error into production damage, service disruption, or exposure of confidential data at machine speed. - Governance as circuit breaker: Explain that governance mechanisms are circuit breakers between agent creativity and real-world consequences: they limit execution until verification occurs. State why auditable logging and human approval demonstrate integrity rather than serving as unnecessary bureaucracy.
Why it matters: Verification, audit trails, and human approval make agent actions accountable to clients, legal teams, and operators before consequences become irreversible.
Key terms: dual-use, authorization, intent, strict governance, CFAA, automation, authorized scope, network boundaries, destructive commands, production systems
2.6.2 Building safety gates
This section defines safety gates and shows a simple gate that blocks critical targets and requires operator approval for other targets before high-risk actions proceed.
- Safety gate purpose: Explain that a safety gate is a checkpoint that enforces review or specified conditions before an agent step is allowed to continue, and distinguish manual gates from automated ones.
Why it matters: Safety gates keep an agent from treating every possible action as automatically authorized. - Critical target blocking: Describe the simple gate's target checks: it automatically blocks actions whose target contains "prod", "payment", or "core-db", while nonmatching targets require explicit operator approval before execution.
Why it matters: This example demonstrates that a gate can combine hard policy-based denial with human authorization. - Gate placement and design: Justify placing the gate inside the act() method or pipeline loop so every high-risk command passes through review, and state the recommendation to design gates before tools so authorization can be expanded later rather than retrofitted.
Why it matters: Putting checks at the execution path and designing them early makes authorization enforceable rather than optional.
Key terms: gate, manual gate, automated gate, safety gate, critical infrastructure, operator approval, prod, payment, core-db, act() method
2.6.3 Sandboxing and isolation
This section explains why approved agent actions still need sandboxing and describes container, process, and offline-simulation isolation strategies.
- Sandboxing as final defense: Explain sandboxing as running agent-generated code in an isolated environment that restricts access to the broader system. Describe why it remains necessary even after safety gates and human approval: agents may execute unreviewed code with dangerous unintended side effects.
Why it matters: Sandboxing contains failures so an agent mistake does not automatically affect the real host or network. - Containerized execution restrictions: Describe containerization as giving an agent an isolated Docker or Podman environment with network limits, resource quotas, and filesystem restrictions. Explain that this lets the agent install tools, run exploits, and generate payloads without affecting the real filesystem or network.
Why it matters: Container restrictions limit the blast radius of tools and payloads an agent executes. - Process and offline isolation: Describe process isolation as dropping privileges and using restricted user accounts rather than giving an agent full permissions. Describe offline simulation as replaying attack logic on synthetic or recorded data before live execution to verify the agent's reasoning chain.
Why it matters: Restricted permissions and pre-live replay provide additional ways to catch or limit unsafe behavior.
Key terms: sandboxing, isolated environment, safety gates, human approval, containerization, Docker, Podman, network limits, resource quotas, filesystem restrictions
2.6.4 Comprehensive logging
This section explains how comprehensive agent logs provide replayable accountability and valuable defensive evidence.
- Replayable agent accountability: Explain why an AI agent must log what it decided, why it chose an action, when the action occurred, and whether it succeeded or failed. Describe how expanding the ArtifactLogger schema with metadata makes actions reconstructable, supports replay and accountability, and helps demonstrate that authorized bounds were respected.
Why it matters: Comprehensive logs let you investigate agent behavior and show that automated actions remained authorized. - Defensive value of offensive logs: Describe how comprehensive offensive-agent logs can help blue teams understand attacker behavior, develop detections, test incident response, and prioritize defensive improvements. Explain the section's point that good offensive data can improve organizational security when defenders can replay and analyze it.
Why it matters: The same records that make offensive work accountable can reveal what defenders should detect, investigate, and fix.
Key terms: ArtifactLogger, schema, metadata, replay, accountability, authorized bounds, defense through transparency, SIEM rules, SOC, incident response
2.6.5 Operational policies
This section defines the operational policies that must be formalized before an agent engagement so AI-assisted security work remains authorized, privacy-conscious, accountable, and responsibly reported.
- Pre-engagement operational policies: State the operational policies that must be written down before an engagement: authorized scope, human approval, data minimization, artifact deletion, and responsible disclosure.
Why it matters: Formal policies turn responsible AI use from an intention into enforceable operating rules. - Authorized scope and approval: Describe how authorized scope limits an agent to written targets, time windows, and prohibited actions, and explain that every run requires at least one human approval gate.
Why it matters: Written scope and human approval prevent an agent from exceeding what an engagement permits. - Data retention and disclosure: Explain the data-handling and reporting policies: do not collect or store unnecessary personal data, purge artifacts after the engagement unless audit needs require retention, and disclose vulnerabilities privately within agreed timelines.
Why it matters: Minimizing sensitive data and reporting findings responsibly reduces harm beyond the immediate technical engagement.
Key terms: authorized scope only, human review, approval gate, data minimization, deletion on completion, responsible disclosure, targets, time windows, prohibited actions, purge artifacts
2.6.6 Implementing kill switches
This section shows how to halt agent operations with a background global kill switch and introduces a pre-run safety checklist.
- Global kill switch design: Describe how the global kill switch provides an immediate manual abort for all agent operations. Explain that agents check a shared active flag, and that setting active=True signals an emergency stop.
Why it matters: A global stop mechanism lets an operator limit harm immediately when an agent behaves unexpectedly. - Background abort monitoring: Explain how the monitor method continuously listens for keyboard input in a background thread while the agent continues normal work. State that typing STOP sets the active flag and stops the agent.
Why it matters: Running the monitor separately keeps an emergency abort available without blocking normal agent execution. - Pre-run safety checklist: State the safety checklist to use before every agent run: defined scope, verified sandbox, configured gate, enabled logging, and an active kill switch. Describe manually running this checklist before automation in later pipelines.
Why it matters: A consistent pre-run check verifies that the basic controls are in place before an agent is allowed to operate.
Key terms: global killswitch, active flag, emergency stop, manual abort, monitor method, keyboard input, STOP, threading library, background, defined scope
2.6.7 Safety and governance summary
This summary consolidates the safeguards that keep an automated agent reviewable, bounded, ethical, and under human control.
- Safety and governance safeguards: Describe how safety gates, sandboxing, comprehensive logging, operational policies, and kill switches collectively govern an automated agent. Explain the distinct protective role of each safeguard.
Why it matters: These controls let an agent act usefully without removing human oversight or acceptable operational boundaries. - Human-controlled automated operation: Explain why the summarized safeguards produce an agent that thinks before acting while remaining under human control, even when it is automated.
Why it matters: Responsible automation requires both useful autonomous processing and the ability for people to review, constrain, and stop it.
Key terms: safety gates, sandboxing, comprehensive logs, operational policies, kill switches, human control, automated systems, responsible agent
2.7 The triage agent
This section introduces the capstone triage agent that combines earlier agent components to rank reconnaissance findings within ethical boundaries.
- Triage agent purpose: Describe the triage agent as an agent that reads reconnaissance data, reasons about which findings matter, and produces a ranked summary while remaining within ethical boundaries.
Why it matters: This frames the concrete security task that the capstone agent is intended to perform. - Integrated triage flow: Explain that the capstone triage agent connects the previously built messages, tools, memory, adapters, and safety gates into one flow, with transitions logged for replay.
Why it matters: Connecting these parts into a traceable flow makes the agent's prioritization process inspectable rather than opaque.
Key terms: triage agent, reconnaissance data, ranked summary, ethical boundaries, messages, tools, memory, adapters, safety gates, logged
2.7.1 What is triage?
This section defines triage as using an agent after reconnaissance to reduce noisy saved results into priorities for human review.
- Post-recon triage purpose: Explain that triage addresses the attention bottleneck after reconnaissance, when large amounts of scan output contain mostly noise but may hide a few important details.
Why it matters: Triage helps focus limited testing time on the results most worth investigating. - Triage agent boundaries: Describe the triage agent as a post-recon assistant that works only on saved output files and helps decide where to focus first; it does not scan, probe, or exploit network resources.
Why it matters: Keeping the agent's role bounded makes its function clear and separates analysis of results from active network actions. - Human judgment and workflow value: Explain that the agent does not replace the security practitioner's skill or judgment; it removes low-value friction from reviewing noise so the practitioner can spend more time validating meaningful findings.
Why it matters: The value of the agent is reclaimed analyst time for validation, not autonomous security judgment.
Key terms: triage, reconnaissance, noise, attention, agent, saved output files, scan, probe, exploit, skill
2.7.2 nmap output
This subsection frames nmap reconnaissance output as noisy input that a narrowly scoped triage agent can review to identify hosts or services worth further investigation.
- Reconnaissance output signal: Explain why typical nmap service-discovery output becomes difficult to review as scope grows, and identify the kinds of details that can be buried in repetitive results.
Why it matters: An agent is useful here because it can focus attention on the few findings that deserve human follow-up. - Narrow triage decision: Describe the agent's narrow task as treating nmap output as a document and identifying hosts or services that stand out enough to justify further investigation, without scanning, exploiting, or assuming later actions.
Why it matters: Keeping the decision narrow makes the agent a triage aid rather than an uncontrolled offensive actor. - Production scan formats: Distinguish the simplified human-readable nmap representation used in this chapter from production structured output, and state that XML or JSON can provide richer metadata while preserving the same triage logic.
Why it matters: Separating decision logic from parsing format lets the same agent approach move from an example to real engagement workflows.
Key terms: nmap output, basic service discovery, unusual ports, legacy services, exposed admin interfaces, AI agent, triage, further investigation, -oX, XML
2.7.3 Agent decision scope and constraints
This section defines a triage agent as a constrained, auditable filter that reduces noisy reconnaissance results to a short list of hosts needing human attention.
- Triage agent mission: Explain that the triage agent is not expected to find vulnerabilities; its practical role is to reduce reconnaissance noise and surface useful signals so a human can make faster, more consistent decisions.
Why it matters: A realistic mission keeps the agent focused on helping human testers prioritize rather than promising autonomous vulnerability discovery. - Reconnaissance signal categories: Describe the signals the agent uses for triage: unusual exposed services or ports, unexpected service combinations, groups of hosts with matching service stacks, and red flags such as legacy, end-of-life, or improperly internet-facing services.
Why it matters: These specific signal types make experienced tester intuition explicit and repeatable during the noisy first pass through reconnaissance data. - Auditable human-centered filtering: Explain that the agent narrows reconnaissance results to a short list of hosts worth attention while leaving a clear trail of how it reached each conclusion, keeping the workflow safe, scoped, and defensible.
Why it matters: A recorded rationale lets people review the agent's prioritization instead of treating its output as an unexplained verdict.
Key terms: triage agent, reduce noise, surface signals, vulnerabilities, unusual exposure, services and ports, odd combinations, service pairings, group similar hosts, service stacks
2.7.4 Triage artifacts
This section defines the prioritized triage summary artifact that turns raw reconnaissance output into an explainable, actionable review list.
- Prioritized triage summary: Describe a prioritized triage summary as the agent’s concise output for quick human review, derived from reconnaissance data and focused on the most promising hosts or services.
Why it matters: It lets an operator begin with likely high-interest targets instead of repeatedly reading raw scan output. - Explainable triage decisions: Explain that each flagged item includes a brief reason for the flag, preserving the agent’s reasoning so a human can agree, disagree, investigate further, or revisit the decision later.
Why it matters: Visible reasons make triage decisions reviewable rather than opaque and reduce the need to reconstruct prior thinking. - Bounded triage output: Distinguish the triage summary from a report, vulnerability list, or severity assessment by stating that it contains no exploit speculation, CVE matching, or severity scoring.
Why it matters: Keeping the output bounded prevents a triage agent from being mistaken for a vulnerability-analysis or exploitation system. - Shared triage reference: Describe how a triage artifact supports individual and team workflows by providing a focused starting point for a hunter and a transparent shared reference for handoffs and collaboration.
Why it matters: A common, explainable artifact helps people coordinate around the same priorities instead of independently reinterpreting raw output.
Key terms: prioritized triage summary, recon data, raw scan output, reasoning, triage decisions, flagged, artifact, exploit speculation, CVE matching, severity scoring
2.7.5 Practical benefits and safety constraints
This section explains how a constrained triage agent speeds recon decisions through consistent, auditable first-pass analysis without replacing human judgment or interacting with targets.
- Recon triage bottleneck: Explain why recon triage, rather than scanning tooling, is often the bottleneck for bug hunters and how the agent shortens the path from completed scans to targets worth testing.
Why it matters: This frames the agent as decision-support automation for the slow, attention-intensive part of reconnaissance. - Consistent explainable triage: Describe how the agent conducts a repeatable first-pass triage by flagging anomalies, grouping similar hosts, and surfacing outliers, while recording decisions and explanations for its flags.
Why it matters: Consistent and explainable prioritization helps testers avoid missed obvious findings and wasted effort on low-value targets. - Constrained human-centered automation: Explain the safety boundaries of the workflow: the agent analyzes only already-collected data, never touches the network, expands scope, or probes targets, and produces inspectable artifacts while leaving judgment and reversible decisions to the human.
Why it matters: These limits make the agent useful for offensive-security triage without turning it into uncontrolled scanning or exploitation automation. - Triage as skill reinforcement: Describe how explicit triage reasoning can help newer bug hunters develop intuition over time rather than substituting for their expertise.
Why it matters: A transparent first-pass workflow can teach practitioners what to look for while preserving their responsibility for final testing choices.
Key terms: recon, triage, raw output, first pass, low-value targets, anomalies, similar hosts, outliers, decision, flag
2.8 Summary
This summary recaps how goal-driven agents combine reasoning, controlled action, reproducible specifications, and engineered safety, illustrated by the Triage Agent.
Where this is used later
- Pipelines vs. scripts (chapter 4) · The later comparison of pipelines and scripts relies on the limitations of fixed script automation.
- Pipeline overview (chapter 3) · The reconnaissance multi-agent pipeline uses staged outputs from reconnaissance through triage and reporting.
- Artifact provenance, replay, and auditability (chapter 3) · Artifact provenance, replay, and auditability build on recorded agent actions and results.
- Artifacts as agent interfaces (chapter 3) · Multi-agent pipelines use artifacts as interfaces between agents.
- The four building blocks to building ReAct agents (chapter 4) · The reconnaissance agent architecture revisits the building blocks of ReAct agents.
- What the orchestrator does (chapter 3) · The orchestrator extends execution coordination across multiple agents.
- Shared state and memory boundaries (chapter 3) · Multi-agent systems establish shared-state and memory boundaries.
- Defense through transparency (chapter 3) · Defense through transparency builds on making agent decisions understandable and inspectable.
Concepts explained in this chapter
- AI agentA software system that applies artificial intelligence to interpret inputs, reason, and take actions, potentially using external tools or data.
- toolAn external software capability that an agent can call to perform an action or obtain an effect outside the language model.
- language modelA large language model is a machine-learning model trained on large text corpora to interpret and generate natural language.
- chain-of-thought promptingA prompting and reasoning technique that elicits intermediate steps to connect a problem statement with a conclusion or action.
- schemaA schema is a formal specification of the structure, fields, and data types permitted in data exchanged between software components.
- JSONLA newline-delimited JSON format in which each line contains one complete JSON object.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
