Overview
AI Agent Instructions define the role, objective, and scope of your AI Agent in plain language. This helps align the agent’s reasoning with your organizational needs and ensures consistency across different workflows. Think of it as the agent’s “job description”: clear, purposeful, and detailed enough to guide its behavior effectively.
In Torq, this is done by filling out the agent Instructions, where you describe the agent’s mission in natural language. A well-written mission statement improves the agent’s ability to choose tools, interpret context, and make decisions aligned with your objectives.
Keep in mind these instructions are general guidelines and suggested starting points, meant to be tailored and refined to match your organization’s specific needs and policies.
Why it matters
Clarity of purpose: Gives the agent clear direction about what it is supposed to accomplish.
Scope definition: Prevents the agent from attempting tasks outside of its intended role.
Context for reasoning: Improves accuracy when selecting tools or interpreting ambiguous instructions.
How to write strong agent instructions
When filling out the agent Instructions, we recommend covering the following elements:
Role: Define the identity or persona of the agent. This helps frame its behavior and decision-making style. Keep it short and explicit. Think of this as the agent’s title or position inside your team.
Example: “An AI SOC Analyst specializing in suspicious login investigations.”
Example: “A Cloud Security Assistant focused on identifying misconfigurations.”
Capabilities: Describe the core outcome the agent should deliver. Be action-oriented and focus on measurable and tangible results. The objective should answer the question: “What success looks like for this agent?”.
Example: “Investigate alerts, enrich observables, and provide remediation recommendations.”
Example: “Respond to phishing incidents by collecting context, confirming with the user, and escalating if needed.”
Rules and constraints: Outline the boundaries, platforms, and situations where the agent should (and should not) act. This keeps it from overstepping into areas it’s not intended for. The scope ensures the agent’s work is targeted and consistent, avoiding drift into irrelevant or unapproved tasks.
Example: “Focus only on endpoint security incidents in CrowdStrike and Okta environments.”
Example: “Assist with IAM-related alerts but do not take action on network or infrastructure logs.”
Guidance: Tell the agent how to perform its role and complete its tasks. While the Role and Capabilities define what the agent is and what it should do, Guidance shapes how it should behave, interact, and sequence its actions.
Example: Start by summarizing the alert in one sentence. Then enrich any available IOCs using the configured tools. Provide a short conclusion with severity, and format the output in Markdown. Keep the tone professional and concise.
Context: The specific case or event details the agent should act on. This gives the agent specific details (date, file, user, platform, policy, etc) so it can tailor its investigation and communication accordingly.
Example: You are investigating a DLP alert triggered on March 12, 2025, at 10:45 AM UTC. The alert flagged a file named
customer_data_export.csvthat was shared externally withexternaluser@gmail.com. The source system is Microsoft OneDrive, and the policy that triggered the alert was “Sensitive Data Shared Externally".
These are suggestions. You don’t need to provide information for every sub-section, only the ones that make sense for your agent.
Tips and best practices
When drafting agent Instructions, keep it simple, practical, and aligned with your team’s real-world workflows. Well-written Instructions make your AI Agent clear and effective.
Keep it natural: Use plain, conversational language and avoid jargon.
Use clear verbs: Frame actions with strong words like investigate, enrich, notify, escalate.
Define role, goal, and scope: Always specify what the agent is, what it should achieve, and where its boundaries lie. Skipping one often leads to vague or unpredictable behavior.
Be specific: Call out the exact systems, workflows, or tasks the Agent should focus on.
Avoid ambiguity: Don’t leave the agent guessing about priorities or responsibilities.
Add examples: Show what the agent should do and how outputs should look. This sets clear expectations, reduces errors, and makes instructions easier to debug, reuse, and optimize.
Align with real processes: Make sure the agent fits into how your team already works instead of creating extra steps.
Be concise and precise: Good grammar and detail go a long way in helping the agent understand your intent.
Keep it simple: No need for ‘please’ or ‘thank you’. While polite, they don’t help the AI and can make agent instructions a bit less clear or efficient.
Maintain a professional tone: Keep it neutral and factual, avoid small talk or off-topic comments.
Using guardrails
Guardrails are clear, explicit instructions in your prompt that shape and control the model’s behavior. They help prevent hallucinations, minimize unnecessary verbosity, and ensure outputs remain consistent, reliable, and safe for downstream automation.
Use best-effort controls to prevent hallucinations
Instruct the model to admit uncertainty when applicable:
If you are not sure about something, respond with: ‘I don’t know.’
Only answer if you have high confidence; otherwise, say ‘I cannot determine that.’
Example
You are a cybersecurity assistant. Only respond with a CVE if you're certain. If you can't identify the vulnerability, say: ‘No match found.’
Control output length
Limit how much the model says, especially important when generating Slack messages, Jira updates, or logs.
Respond in no more than 100 words.
Summarize in 2–3 bullet points max.
Return only a single paragraph.
Example
Summarize this incident report in under 3 bullet points for SOC review. Be concise, clear, and avoid speculation.”
Enforce output format
Help downstream tools parse the output reliably:
Respond in JSON with these fields: severity, recommendation.
Use this Markdown template: ### Summary | ### Action Items.
Do not include any commentary outside the structured output.
Example
Return the result in strict JSON format:
{ "threat_level": "low", "actions": ["Monitor login attempts"] }
Do not add explanations outside the JSON block.
Control tone and formality
Keep tone appropriate for internal teams or end users:
Use a formal tone suitable for a SOC analyst.
Be neutral and professional, avoid exclamation marks.
Example
Draft a Slack message about this alert. Be neutral and factual, not alarming. Avoid phrases like ‘critical failure’ unless severity = high.
Minimizing hallucinations
Hallucinations occur when an agent generates plausible-sounding but incorrect or fabricated output. These guidelines reduce that risk at both the instruction and setup levels.
Instruct the agent not to guess
Explicitly tell the agent not to assume or fill in missing information. If the data needed to complete a task is not available, the agent should say so rather than fabricate an answer.
If the required information is not available in the provided context or tool output, respond with: "I don't have enough information to answer this."
Do not infer, assume, or approximate values that are not explicitly present in the data.
Validate your tools
Make sure every tool the agent has access to is actually needed, correctly configured, and returns exactly the data required, no less, and no more. Tools that return excessive or irrelevant data increase the risk of the agent misinterpreting or hallucinating from noisy output. Before deploying an agent:
Confirm that each tool is present and returns the expected output.
Remove any tools that are not actively used by the agent's mission.
Check that tool outputs are scoped precisely to what the agent needs.
Prefer mission-specific agents over generalist agents
Narrow, mission-oriented agents perform better than broad, generalist ones. A focused agent has a clearer scope, uses fewer tools, and is easier to evaluate and debug. If an agent requires more than approximately 15 tools, that is a signal that it is trying to do too much. Split it into multiple, purpose-built agents instead, each with its own focused mission, tool set, and instructions.
Creating goal-oriented agents
Build AI Agents that are finely tuned to your organization’s unique needs, processes, and terminology. Instead of relying on generic behavior, you can guide the agent to operate within the context of your environment. By focusing on a clear goal, such as SOC operations (e.g., triaging alerts and enriching observables), IT automation (e.g., managing user accounts or provisioning resources), or compliance (e.g., auditing access logs and generating reports), you ensure that the Agent is equipped with:
Relevant tools that connect directly to the workflows and systems your teams rely on.
Contextual knowledge that helps the agent understand how tasks fit into broader processes.
Behavioral guidelines that shape how the agent responds, prioritizes, and interacts with users.
Example
Instead of one Agent that "handles alerts triage," break it into three agents:
Enrichment Agent
Communication Agent
SOC interaction agent
Instead of one Phishing Agent, create:
Suspicious Intent Analyzer
IOCs Analyzer
Attachments Analyzer
SOC Interaction Agent
How to use
Open the agent: Go to Build > AI Agents and click the agent you want to configure.
Write instructions: In the Instructions panel, define the agent's behavior. At minimum, fill out the following fields:
Role: Define the agent's persona (for example, "security analyst" or "support engineer").
Goal: Describe the primary objective the agent should accomplish.
Guidance: Provide structured instructions that define how the agent should act, communicate, and sequence its actions to achieve the goal.
For additional fields that help refine agent behavior, see How to write strong agent instructions above.
(Optional) Reference a parameter: Type @ anywhere in the Instructions panel to open the parameter picker and insert a parameter reference inline. At runtime, the agent replaces each reference with the value passed by the caller.
(Optional) Define a JSON schema: In the Output tab, specify the JSON schema the agent must follow for its output. See Output JSON schema below.
Save: Click Save to apply your changes.
Test: Click Test Run to run the agent immediately.
Review the run: Open the Log tab to inspect the execution flow, validate the agent's reasoning, verify tool selection, and confirm expected behavior before publishing to production.
The agent instructions are saved and will take effect the next time the agent runs. Publish the agent to make it available across the platform.
Output JSON schema
The optional Output parameter lets you define a strict JSON Schema that controls how an AI Agent structures its output. When provided, the agent generates results that conform to the specified schema, including field names, data types, required properties, and nested objects, so downstream steps can reliably parse and consume the output.
Define the schema: In the Output tab, enter a JSON Schema that defines the expected output structure, including field names, data types, required properties, and nested objects.
Validate and refine: Review the schema to ensure it matches the exact structure required by downstream steps or tools.
Run and verify: Click Test Run to run the agent right away and confirm that the Agent output conforms to the defined schema. If the output doesn’t match, the Agent will retry or surface an error, depending on execution behavior.
Example
This section outlines how to configure a DLP Communication Security Agent in Torq. The agent’s purpose is to interact with users when a Data Loss Prevention (DLP) alert is triggered, gather context around the incident, and determine whether the activity poses a risk.
Role
You are a DLP Communication Security Agent. Your job is to engage with the source user of a Data Loss Prevention (DLP) alert, investigate their intent, and determine whether the event is legitimate or poses a security risk.
Capabilities
Introduce yourself to the user and explain the alert details (date, what was shared, destination, and why it may be risky).
Investigate the incident by asking up to three targeted clarification questions, one at a time, and stop early if the explanation is justified.
Summarize the user’s explanation and assess whether risk remains.
Conclude with a professional closing message thanking the user.
Parameters
Name | Type | Required | Description |
| Short text | Yes | Email address of the user associated with the DLP alert |
| Short text | No | Name of the organization, used in the agent's introduction. Defaults to your organization name. |
Guidance
Introduction: Introduce yourself as: “I’m Torq, the AI Agent of the Security team at
@company_name.”Explain the alert clearly: Include details such as:
Date and time of the alert
File(s) shared (if any)
Who the file was shared with
Why the action could be risky
Investigate with respectful questions: Examples include:
Confirming if they performed the action
Asking for their business justification for sharing the file
Clarifying intent, data sensitivity, or whether the sharing was meant to be external
Summarize neutrally: Provide a balanced summary of the user’s explanation and whether the intent appears justified.
Closing: End with: “Thank you for your cooperation, your honest response is appreciated.”
Rules and constraints
Ask no more than 3 questions, one at a time.
Always maintain confidentiality, professionalism, and a respectful tone.
Context
Contact the user at @user_email.