Best Practices

​

Overview

1. Agent Instructions – Crafting Roles & Constraints
2. Abilities (Tools) & Handling Large Outputs
3. Knowledge Base (RAG) vs. Direct Context Injection
4. Agent Role vs. Agent Task

​

1. Agent Instructions – Crafting Roles & Constraints

​

1.2 Agent Roles- The Core Guardrails for Prompts

<role>
Define WHO the agent is, its core domain, and its operational boundaries.
</role>

<context>
Explain WHY this agent is running and what ecosystem it sits within.
</context>

<behavior>
Define HOW the agent thinks, its epistemic standards, and its approach to uncertainty.
</behavior>

<mandatory_abilities>
Hardcode the exact tools the agent MUST run before delivering an answer.
</mandatory_abilities>

<quality_bar>
The final self-verification checklist executed at runtime.
</quality_bar>

• Do not just say “be accurate.” Define the evidence-driven threshold.
• Enforce negative constraints explicitly (e.g., forbidding speculation on attribution without specific indicators).

<behavior>
- Be evidence-driven, analytical, and highly concise.
- Do not speculate or infer facts not explicitly supported by the data provided.
- Do not dismiss findings solely because a single indicator looks benign.
- Consider cumulative evidence—never evaluate security indicators in isolation.
- If evidence is incomplete, reflect that uncertainty in your confidence scores but still provide the best-supported analysis.
- Do not reveal your chain-of-thought in the final payload response.
</behavior>

• Write items as binary pass/fail conditions.
• Mirror constraints: if a tool call or rule is mandatory elsewhere in the prompt, it must have a matching verification item in the quality bar.
• Placement: Always place the <quality_bar> tag at the end of the “Constraints” field so it executes last.

<quality_bar>
Before returning output, verify and ensure:
- All tools specified in <mandatory_abilities> were called before generating the answer.
- No analyst triage question was left unaddressed.
- The output strictly adheres to the JSON format defined in the output schema.
- No answer contains speculation, assumptions, or unsupported inferences.
</quality_bar>

<risk_assessment_criteria>
Evaluate the security alert and respond with TRUE or FALSE for each of the following criteria:
1. IS_PROD: Is the affected asset a production environment?
2. EXPLOITED: Is there active evidence of exploitation in the wild?
3. PRIVILEGES: Does the attacker have administrative or root access?
4. SENSITIVE_DATA: Does the asset contain PII, financial data, or credentials?
</risk_assessment_criteria>

<severity_scoring>
Assign a severity score from 1 to 5 based strictly on the definitions below:
1 - Low: Informational alert, no evidence of compromise, non-prod asset.
2 - Minor: Anomalous behavior detected on non-critical asset; isolated incident.
3 - Medium: Potential compromise of a standard user account or non-prod server with no data exfiltration.
4 - High: Confirmed compromise of a corporate asset or production service; potential data access.
5 - Critical: Confirmed compromise of a Domain Controller, core database, or executive account; active data exfiltration.
</severity_scoring>

​

1.2 Agent Task: Inputs & Runtime Constraints

<closing_reason_options>
={{ conclusion_summary }}
</closing_reason_options>

​

1.3 Agent Task: Output Schemas

• Do not use type names (like "string", "int", or "float") or descriptive ranges (like "0-100") inside your example values. The schema builder interprets your values literally — if you write "float", the system will expect a literal text string of "float". Instead, use actual, valid sample data to dictate the type.
• Don’t stress too much about strict string-to-number validation for downstream steps. Blink includes built-in type coercion: if the LLM outputs a number wrapped as a string (like "36.5" or "0"), Blink will automatically convert it to a true number when passing it into the next automation input.

• Strings: Provide a realistic sample text string (e.g., "Suspicious activity detected").
• Numbers: Provide a literal valid number (e.g., 1 for integers, 3.5 for floats).
• Enums: Use an explicit, human-readable instruction followed by comma/pipe-separated values (|) to strictly define allowed choices.
• Include reference to parameters.

{
  "summary": "[brief_summary_of_why_the_ip_is_flagged_or_not]",
  "intent": "Must be one of the following: Malicious | Benign | Duplicate | Inconclusive",
  "risk": {
    "risk_score": 85,
    "risk_severity": "Must be one of the following: Low | Medium | High | Critical"
  },
  "closing_reason": "Must be one of the following: Escalated | Automatically resolved | False positive | Duplicate | No action needed",
  "closing_reason_confidence_score": 0.95
}

​

1.4 Modular Prompting with Agent Skills [UPCOMING]

• Old Way (Monolithic): The agent prompt contains the role, the behavior, and detailed instructions for every tool it might use.
• New Way (Skill-Based): The agent prompt contains only the operational kernel (core identity, reasoning standards, and a coordination routing framework). The specific context, constraints, and execution parameters for a capability live inside the Skill definition itself.

​

2. Abilities (Tools) & Handling Large Outputs

​

2.1 Designing Agent Abilities

• Provide sufficient context: Ensure the name and description explicitly state what the workflow does, what it requires, and when it should be used so the agent can accurately decide if it’s the correct tool for the job.
• Call out side-effects: If a workflow performs a disruptive or state-changing action (e.g., blocking an IP, disabling a user account, or sending an external notification), you must explicitly state this side-effect in the name or description. This prevents the agent from accidentally triggering high-impact actions during passive analysis.

<mandatory_abilities>
You MUST execute this ability before finalizing your analysis:
- <ability_call>get_vip_users</ability_call>: Retrieves the organization's high-risk/VIP user list to cross-reference asset ownership.
</mandatory_abilities>

​

2.2 Handling Large Outputs & Context Window Mitigation

1. Deterministic filtering:
   • Use optimized platform utilities (JQ or explicit API server-side filtering parameters) to extract only relevant keys or anomalous rows.
   • Always prioritize inputs that fit natural human reasoning over raw system formats. For example, design the tool to accept a human-readable timestamp (e.g., "2026-06-29" or "2 hours ago") rather than a raw Epoch timestamp (e.g., 1782741741). While an LLM can sometimes convert time, it is highly prone to hallucination and mathematical errors when dealing with unix timestamps. It is always better to design the ability to accept clean, readable strings, and handle the necessary technical conversions (like translating text to Epoch) in the very first step of your underlying workflow.
2. Agent-guided filtering:
   • Turn on ability compaction — it simplifies lengthy or detailed results from the ability, allowing the agent to focus on the most important information. In addition, provide compaction instructions to help the agent decide what’s important in this ability’s results.
   • Let a fast, cheap model parse a subset of lines to isolate the exact timestamps or signatures required before passing the clean block to the core reasoning agent.

1. Advanced Math & Analytics (“No Mental Arithmetic”)
   • The problem: When tasked with complex calculations (e.g., Quarter-over-Quarter growth, financial forecasting, or statistical analysis), LLMs often struggle with precision or hallucinate numbers when doing math “in their head.”
   • The solution: The agent extracts the raw data and dynamically generates a Python script to perform the exact calculation. It treats the LLM as the strategist and the Python engine as the calculator, ensuring 100% mathematical accuracy.
2. High-Volume Data Filtering & Extraction (“Context Slimming”)
   • The problem: A tool returns a massive payload — like thousands of raw log lines or an entire database dump — but the agent only needs a fraction of it. Passing all that data into the agent’s context window blows through tokens and increases cognitive load.
   • The solution: The agent writes a precise JQ query or Python script to filter, slice, and extract only the relevant data points before they hit the context window, keeping the agent lean and fast.
3. Multi-Source Data Cross-Checking (“Hard Joins”)
   • The problem: Correlating disparate data sets (e.g., joining an IT incident log with office badge-in times and asset owner databases) requires tracking complex relationships that easily overwhelm an LLM’s memory.
   • The solution: Instead of trying to “hold the data in its head,” the agent builds a custom script to programmatically merge and cross-reference the data sources, outputting only the final, correlated insight.
4. Bulk Execution & Loop Unrolling (“Overcoming Rate Limits”)
   • The problem: An agent has a static ability to perform a single action (e.g., Send Slack Reminder), but it needs to perform that action 100 times. Running 100 consecutive tool calls will hit platform limits, time out, or drain tokens.
   • The solution: The agent adapts by writing a new, bulk-ready ability on the fly (e.g., Send Bulk Slack Reminders). It takes the full list of 100 users as a single input, executes the loop securely in the background, and resolves the task in a single tool call.
5. High-Volume Templating & Generation (“Heavy Lifting Delegation”)
   • The problem: The user needs a large, heavily structured output where only a small part is dynamic (e.g., a massive HTML email template or a structured JSON payload where only a few variables change). Making the LLM generate the entire static block is a waste of tokens.
   • The solution: The agent crafts the core dynamic content, then writes a quick automation script to inject that content into the larger static template. The agent only “thinks” about the meaningful parts, while the engine handles the boilerplate.

​

3. Knowledge Base (RAG) vs. Direct Context Injection

​

3.1 The Core Dilemma: Search vs. Certainty

​

3.2 When to Use a Knowledge Base (VectorDB)

• Massive corp data / historical logs: Large repositories of past threat intelligence reports, internal asset vulnerability contexts, or extensive corporate network architecture documentation.
• Payloads > 15–20KB: High-volume data that would completely bloat the prompt, degrade model performance, and spike runtime token costs if included on every single execution.

• ✅ Good practice: Well-formatted Markdown is excellent for this.
• ❌ Bad practice: Low-effort “dumps,” such as copy-pasting raw text straight from a website alongside a bunch of unrelated navigation garbage, ads, or footers, will severely degrade embedding quality. Take the time to strip out the noise so the agent only processes highly relevant text.

​

3.3 When to Avoid a KB: The Case for Direct Context Injection

• The core playbook/manual: The exact, sequential steps an agent must follow during an active incident (e.g., Phishing Triage Guidelines).
• Deterministic execution: Any instruction where missing a single step or constraint means an operational failure. Direct context guarantees the model processes the rule on every single run.
• High-context tools: When an LLM evaluates a specific alert and asks itself, “How do I respond to this phishing attempt?”, a KB search might retrieve irrelevant historical phishing files. Direct context instead enforces immediate execution of your designated block_sender tool logic.

​

3.5 Quick-Reference Framework: VectorDB vs. Direct Context

​

4. Agent Role vs. Agent Task

​

4.1 The Separation of Concerns: Static Identity vs. Dynamic Execution

• The Agent Role (the identity): This is the compile-time configuration. It defines the agent’s domain expertise, behavioral constraints, reasoning frameworks, and tool boundaries. It is permanent, generic to the domain, and wrapped in standard XML tags (<role>, <behavior>).
• The Agent Task (the mission): This is the runtime instantiation. It defines the specific ticket, alert, data artifact, or objective the agent must process during this specific execution cycle. It is transient, injected dynamically.

​

4.2 Designing the Boundary in Blink Workflows

1. The core agent configuration (the Role) — The prompt template defines the persona and how it processes tasks, using a generalized placeholder to ingest the runtime mission (see Agent Roles for more information).
2. The runtime injection (the Task)

<current_task>
OBJECTIVE: Evaluate the attached CloudTrail snippet for potential session hijacking on the user 'admin-ci-cd'.

REQUIRED OUTPUT ACTIONS:
- Check if the source IP has historically performed successful auth actions.
- Determine if the user's active session should be revoked.
- Populate the output schema with your risk recommendation.
</current_task>