> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-xdr/learn-about-cortex-xdr/agentic-ai-in-cortex-xdr/best-practices-for-using-agentic-ai-in-cortex-xdr.md).

# Best practices for using Agentic AI in Cortex XDR

Agentic AI brings AI agents into Cortex XDR. Agents work with the same cases, issues, assets, data, playbooks, scripts, and integrations that you already use, and they follow the same permissions as your users. The more complete your Cortex XDR environment is, the more your agents can do.

Use these practices to roll out Agentic AI safely, build agents your team trusts, and get measurable value from them.

{% hint style="info" %}
**Key concepts**

* **Agent:** An AI persona that builds and runs a plan to complete your request.
* **Action:** A playbook, script, integration command, or AI prompt that an agent can run.
* **Plan:** The steps an agent chooses to complete a request. You can review the plan in the chat.
* **Knowledge:** Your organization's documents, such as SOPs, that agents use for context.

For more information, see [Agentic Assistant components and concepts](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/configure-cortex-xdr/configure-and-deploy-cortex-xdr/configure-the-cortex-agentic-assistant/agentic-assistant-components-and-concepts).
{% endhint %}

## Prepare your environment

Agents can only use content that's installed, configured, and allowed by your permissions. Set up the foundation before you invite users.

* **Enable the Agents & LLM Experience.** Go to **Settings** → **Configurations** → **General** → **Server Settings** → **AI Configuration**.
* **Connect the integrations your agents need.** Actions that use an integration command work only when that integration is installed and active. In the **Agentic Assistant Hub**, open each system agent that you plan to use and look for actions with the **Unavailable content** status. Install and configure only the content packs that are relevant to your organization. For more information, see [Manage agents](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/configure-cortex-xdr/configure-and-deploy-cortex-xdr/configure-the-cortex-agentic-assistant/agents-hub/manage-agents).
* **Add more actions from Marketplace.** In **Marketplace**, filter by **Content pack includes** → **Actions**.
* **Confirm that user roles and scopes are correct.** Agents run with the permissions of the user who invokes them. If a user can't access a dataset, asset, or case, the agent can't access it for that user either.

## Roll out access in stages

Configure role-based access control (RBAC) before you give users access to agents. In the role settings, the **Cortex Agentic Assistant** permissions let you separate who uses agents from who builds and manages them.

| Permission               | Recommended for                                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------ |
| **Interact with agents** | Analysts who chat with agents.                                                                               |
| **Manage actions**       | Automation engineers who turn scripts, commands, and AI prompts into actions.                                |
| **Manage agents**        | Users who build their own custom agents.                                                                     |
| **Agents admin**         | A small group that owns agent quality, enables or disables system agents and actions, and manages knowledge. |

We recommend that you start with a pilot group that has **Interact with agents** and uses the system agents. Expand access as your team gains confidence. For more information, see [Agentic Assistant role-based access control](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/configure-cortex-xdr/configure-and-deploy-cortex-xdr/configure-the-cortex-agentic-assistant/agentic-assistant-role-based-access-control).

## Start with system agents

System agents are ready to use and are designed for common security operations tasks.

* **Choose the agent that fits the task.** For example:
  * Use the **Help Center** agent to answer product questions and open a support case.
  * Use the **Automation Engineer** agent to create scripts and playbooks.
* **Tailor system agents to your team.** Add specific instructions to a system agent to set its tone, output format, and priorities.
* **Disable agents you don't use.** A shorter agent list helps analysts choose the right agent quickly.

For more information, see [Choose an Agentic Assistant agent](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/detect-investigate-and-respond-to-threats/agentic-assistant-chat/choose-an-agentic-assistant-agent).

## Build focused custom agents

Build custom agents when your team has a repeatable workflow that the system agents don't cover.

* **Build one agent for each workflow.** An agent can only use the actions assigned to it and can't call other agents. Assign every action that the workflow needs, and nothing more.
* **Separate investigation from response.** For example, create a read-only agent that gathers information, and a separate agent that can take response actions.
* **Write clear specific instructions.** Describe three things:
  * **Role:** Who the agent is. For example, "You are a SOC tier 1 analyst responsible for triaging alerts and deciding whether each alert is a true or false positive."
  * **Instructions:** How the agent works. For example, "Follow the NIST framework and give clear, concise recommendations."
  * **Structure:** How the agent formats its response. For example, Markdown tables or JSON.
* **Add conversation starters.** Add up to four example prompts that show users what the agent can do.
* **Add the XQL action when the agent needs to query data.** A custom agent can run XQL queries only if you assign the **Cortex - Run XQL Query** action. System agents include this action by default.
* **Share agents deliberately.** Custom agents are private by default. Make an agent public when your team should use it. Only public agents are available in Slack.

For more information, see [Build agents](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/configure-cortex-xdr/configure-and-deploy-cortex-xdr/configure-the-cortex-agentic-assistant/agents-hub/build-agents).

## Turn your automation into effective actions

Your existing playbooks, scripts, and integrations are what make agents useful. When you register them as actions, help the agent understand when and how to use each one.

* **Describe the action clearly.** Give each action a short, specific **Name** and a clear **Goal**. Add **Few-shot examples** that show when the agent should use the action.
* **Expose only the parameters that the agent needs.** Select only the inputs and outputs that matter, add descriptions where they're missing, and set default values. Focused actions lead to more accurate plans.
* **Reuse actions where possible.** When you register content that's already registered, Cortex XDR shows the existing actions. Check whether one of them meets your needs before you create a new one.
* **Restrict powerful commands to specific roles.** Use integration permissions to control which roles can run actions that are based on integration commands.

For more information, see [Register actions](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/configure-cortex-xdr/configure-and-deploy-cortex-xdr/configure-the-cortex-agentic-assistant/agents-hub/register-actions) and [Manage actions](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/configure-cortex-xdr/configure-and-deploy-cortex-xdr/configure-the-cortex-agentic-assistant/agents-hub/manage-actions).

## Keep people in control of changes

AgentiX is designed so that agents never have more access than the user who runs them. Use these controls to keep your team in charge of changes to your environment.

* **Require approval for actions that change your environment.** New actions are marked as sensitive by default, which means a user must approve them before they run. Keep this setting for any action that changes systems or affects cost, such as isolating an endpoint or revoking user access. You can change this setting for each action in the **Agentic Assistant Hub**.
* **Avoid unnecessary approvals for read-only actions.** Clear the sensitive setting only for actions that don't change anything, such as enrichment lookups. This keeps analysts focused on the approvals that matter.
* **Review MCP tools before you remove approval.** Actions created from MCP server tools are also marked as sensitive by default.
* **Verify AI output before you act on it.** Treat agent findings, summaries, and generated queries as a starting point. Train analysts to review AI-generated content critically, especially before they approve an action.
* **Review the plan.** In the chat, expand **Plan** to see how the agent understood your request, which steps it planned, and which actions it used.
* **Audit agent activity.** Every action an agent runs is recorded, including which agent ran it and which user invoked it.

For more information, see [Agentic Assistant security](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/learn-about-cortex-xdr-5.x/agentic-ai-in-cortex-xdr/agentic-assistant-security).

## Write effective requests

The quality of an agent's plan depends on the quality of your request.

* **State the goal, scope, and output.** For example, "List high-severity issues from the last 24 hours where the hostname includes 'server', and show them in a table."
* **Combine steps in one request.** Agents can plan multi-step work. For example, "Investigate this phishing issue, find the source of the email, and block any malicious indicators."
* **Start from the right place.** Open the Agentic Assistant from a case so the agent starts with the relevant context.
* **Be explicit when you want a query.** Use phrases such as "Create an XQL query to…" or "Build an XQL query for…". Agents generate queries for system datasets. For custom datasets, write the query yourself and ask the agent to run it.
* **Choose the right model.** If your region supports the model selector, choose a model for each chat based on the task. For available models, see [Agentic AI in Cortex XDR](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/learn-about-cortex-xdr-5.x/agentic-ai-in-cortex-xdr).

For example prompts, see [Agentic Assistant use cases](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/learn-about-cortex-xdr-5.x/agentic-ai-in-cortex-xdr/agentic-assistant-use-cases) and [Create and run XQL queries with Agentic Assistant chat](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/detect-investigate-and-respond-to-threats/agentic-assistant-chat/create-and-run-xql-queries-with-agentic-assistant-chat).

## Choose between playbooks, AI prompts, and agents

Use each capability for the work it does best. Many teams combine all three.

| Use                              | When                                                                     | Example                                                                                    |
| -------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| **Playbook**                     | The workflow is known and should run the same way every time.            | Triage every new phishing issue.                                                           |
| **AI prompt task in a playbook** | A playbook step needs reasoning over data that the playbook already has. | Extract indicators from an email body, then branch on the result.                          |
| **Agent**                        | The task is ad hoc, exploratory, or doesn't follow a fixed workflow.     | "Read this threat report, find the CVEs, and check whether any of my assets are affected." |

When you add AI prompt tasks to playbooks:

* **Pass only the data that the prompt needs.** Map inputs to specific context keys, such as `${issue.creation_date}`, instead of the whole issue. This improves accuracy and reduces cost.
* **Use the Optimize button** in the prompt editor to improve your prompt's wording.
* **Follow the prompt with a logic step.** AI prompt tasks can't take actions or make branching decisions, and they always return text. Add a parsing script or conditional task after the prompt.
* **Configure retries.** Set **On Error** retries for the task.

For more information, see [Write effective prompts](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/detect-investigate-and-respond-to-threats/investigate-and-respond-to-cases/automation/ai-prompts/write-effective-prompts) and [Add AI Prompt tasks](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/detect-investigate-and-respond-to-threats/investigate-and-respond-to-cases/automation/playbooks/build-your-playbook/add-objects-from-the-task-library/add-ai-prompt-tasks).

## Use AI to build and improve automation

* **Create scripts faster.** Ask the Automation Engineer agent to draft, refine, and deploy Python scripts from a natural language description. For more information, see [Accelerate script development using the Automation Engineer agent](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/detect-investigate-and-respond-to-threats/investigate-and-respond-to-cases/automation/scripts/accelerate-script-development-using-the-automation-engineer-agent).
* **Create and improve playbooks (preview).** Open a playbook in edit mode and describe what you want the Agentic Playbook Builder to create or change. Refine the result with follow-up requests instead of trying to write a perfect first prompt. If the builder can't find the content it needs, it adds a placeholder task for you to complete. Playbooks that the builder creates or changes are tagged **AI Assisted**, and you can compare or revert revisions. For more information, see [Accelerate playbook development using the Agentic Playbook Builder](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/detect-investigate-and-respond-to-threats/investigate-and-respond-to-cases/automation/playbooks#agentic-playbook-builder-for-playbook-development-preview).\
  Note: The Agentic Playbook Builder preview feature is not enabled by default. To request access, contact [Cortex Product Management](mailto:dl-CortexAgentixDesignPartners@paloaltonetworks.com).
* **Test AI-generated content before production.** Review and test generated scripts and playbooks the same way you test any other change. For more guidance, see [Best practices for playbooks](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/detect-investigate-and-respond-to-threats/investigate-and-respond-to-cases/automation/playbooks/best-practices-for-playbooks).

## Give agents your organization's knowledge

* **Ground agents in your procedures (preview).** In the **Knowledge Center**, upload SOPs, policies, frameworks, and analyst notes, or link pages from Confluence or Google Drive. Supported file types are MD, JSON, JSONL, CSV, DOC, and DOCX, up to 5 MB per file. The Knowledge Center is in preview and isn't enabled by default.
* **Keep knowledge current.** Turn on **Auto sync** for linked sources so that agents use the latest version.
* **Share knowledge only with the agents that need it.** Monitor your tenant's source limit in the Knowledge Center.
* **Check the sources.** Agent responses include labels that show which knowledge was used.

For more information, see [Manage knowledge sources (preview)](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/configure-cortex-xdr/configure-and-deploy-cortex-xdr/configure-the-cortex-agentic-assistant/agents-hub/manage-knowledge-sources-preview).

## Extend agents with MCP integrations

Connect third-party MCP servers so that agents can retrieve data and take actions in other tools, such as GitHub, Atlassian, or Cloudflare.

* **Separate read-only and read-write access.** Create one integration instance for read-only tools and a separate instance for tools that make changes.
* **Assign MCP tools only to the agents that need them.** MCP tool actions are available only to the custom agents you add them to.
* **Restrict MCP tools to specific roles.** Use integration permissions to limit which roles can use them.
* **Make sure tools are well described.** Cortex XDR creates actions only from MCP tools that have input and output descriptions.

For more information, see [Expand agent capabilities with MCP integrations](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/configure-cortex-xdr/configure-and-deploy-cortex-xdr/configure-the-cortex-agentic-assistant/agents-hub/expand-agent-capabilities-with-mcp-integrations).

## Bring agents into your team's daily work

* **Work with agents in Slack.** After you set up the Slack v3 integration, tag your bot in a thread to work with a public agent. Keep the following in mind:

  * Each user's Slack email address must match their Cortex XDR user email.
  * Only the user who starts the session can send requests and approve sensitive actions.
  * To hand off the session, type `@<bot name> reset`.
  * The agent uses the last five messages in the thread for context.

  For more information, see [Chat with the Agentic Assistant from Slack](https://cortex-docs.paloaltonetworks.com/cortex-xdr-5.x/detect-investigate-and-respond-to-threats/agentic-assistant-chat/chat-with-the-agentic-assistant-from-slack).
* **Use agents at the start of every shift.** For example, ask "What are the top issues I should prioritize today?", "Show me all issues with an overdue SLA", or "Which automations are waiting for my input?"

## Measure and improve

* **Track usage.** Review agent activity in the audit records to see which agents and actions your team uses most and where users deny approvals.
* **Improve what isn't working.** If an agent often picks the wrong action, improve that action's goal, few-shot examples, and parameter descriptions. Refine agent instructions based on analyst feedback.
* **Remove what isn't used.** Disable agents and actions that nobody uses.
* **Manage cost.** Running XQL queries through an agent doesn't consume compute units. In AI prompt tasks, pass only the context keys that the prompt needs.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://cortex-docs.paloaltonetworks.com/cortex-xdr/learn-about-cortex-xdr/agentic-ai-in-cortex-xdr/best-practices-for-using-agentic-ai-in-cortex-xdr.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.