> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Agents

> Step-by-step guide to creating your first agent

## Prerequisites

Before creating an agent, you should:

<Steps>
  <Step title="Connect Integrations">
    Authenticate the tools your agent will use (Jira, Splunk, SentinelOne, etc.)

    Navigate to **Settings > Integrations** and connect relevant services
  </Step>

  <Step title="Define the Use Case">
    Be clear about what the agent should do:

    * What problem does it solve?
    * What triggers it?
    * What tools does it need?
    * What output should it produce?
  </Step>

  <Step title="(Optional) Prepare Context Docs">
    If your agent needs reference material (runbooks, policies, FP lists), have those ready in Google Docs or Notion
  </Step>
</Steps>

## Creation Methods

You can create agents in three ways:

<CardGroup cols={3}>
  <Card title="From Chat (Recommended)" icon="messages">
    Convert a successful chat session
  </Card>

  <Card title="From Scratch (Advanced)" icon="wand-magic-sparkles">
    Build a custom agent with full control
  </Card>

  <Card title="From Template" icon="copy">
    Start with a pre-built template
  </Card>
</CardGroup>

<Note>
  **Prefer to manage agents as code?** You can also define response agents as YAML in your own GitHub repo and let Cotool sync them in. See [Response Agents as Code](/agents/response-agents-as-code).
</Note>

## Method 1: Create From Scratch

<Steps>
  <Step title="Navigate to Agents">
    Click **Agents** in the sidebar, then **Create Agent**
  </Step>

  <Step title="Basic Information">
    Fill in the basics:

    **Name**: Short, descriptive name (e.g., "SentinelOne Alert Triage")

    **Description**: What does this agent do? Who uses it?
  </Step>

  <Step title="Write System Prompt">
    This is the core of your agent. Write clear instructions about:

    * The agent's role
    * What it should do
    * When to use which tools
    * How to format output

    <Card href="/core-concepts/system-prompts">
      **Prompt Engineering Guide** → Learn how to write effective prompts
    </Card>
  </Step>

  <Step title="Select Tools">
    Choose which tools the agent can use:

    * Browse by category (SIEM, EDR, Ticketing, etc.)
    * Or search by name
    * Grant only what's needed for the task

    **Tip**: Start with fewer tools, add more as needed
  </Step>

  <Step title="Attach Skills (Optional)">
    Add reusable skills when part of the workflow should stay consistent across multiple agents:

    * Standard investigation procedures
    * Output formats and reporting templates
    * Reusable enrichment or triage playbooks

    Cotool will warn you if a selected skill requires tools this agent does not have.

    <Card href="/agents/skills">
      **Learn about Skills** -> Reusable instructions and resources for agents
    </Card>
  </Step>

  <Step title="Add Context Documents (Optional)">
    Link Google Docs or Notion pages that provide reference information:

    * Runbooks and procedures
    * Known false positive lists
    * Contact directories
    * Policy documents

    The agent will have access to these during execution
  </Step>

  <Step title="Configure Settings">
    **Planning Mode**:

    * `never`: Agent acts immediately (faster, good for simple tasks)
    * `auto`: Agent decides if planning is needed
    * `always`: Agent always creates a plan first (better for complex tasks)

    **Max Tool Calls**: Limit how many tools the agent can call (default: 25)

    **Timeout**: Maximum execution time (default: 5 minutes)
  </Step>

  <Step title="Save and Test">
    Click **Create Agent**. You'll be taken to the agent detail page.

    Next, test it using the **Builder** interface!
  </Step>
</Steps>

## Method 2: Create From Template

Templates are pre-built agents for common use cases:

<Steps>
  <Step title="Browse Templates">
    Click **Agents** > **Create Agent** > **From Template**
  </Step>

  <Step title="Choose Template">
    Select from templates
  </Step>

  <Step title="Customize">
    Templates come with:

    * Pre-written system prompt (edit to fit your needs)
    * Recommended tools (add/remove as needed)
    * Example context documents

    Customize these for your environment
  </Step>

  <Step title="Configure Integrations">
    Ensure you have the required integrations connected (template will list them)
  </Step>

  <Step title="Test & Deploy">
    Use Builder to test with real data, then set up triggers
  </Step>
</Steps>

<Card href="/use-cases/alert-triage">
  **Browse Use Cases** → See common agent patterns
</Card>

## Method 3: Create From Chat

If you've had a successful chat session, convert it to an agent:

<Steps>
  <Step title="Complete Chat Session">
    Use the Chat interface to work through your use case
  </Step>

  <Step title="Review the Session">
    Make sure the chat achieved the desired outcome with good tool usage
  </Step>

  <Step title="Click 'Create Agent'">
    In the chat interface, click **Create Agent from Chat**
  </Step>

  <Step title="Auto-Generated Prompt">
    Cotool analyzes the chat session and generates:

    * System prompt based on your conversation
    * Tool list from what was used
    * Planning mode based on complexity
  </Step>

  <Step title="Refine and Save">
    Review the generated prompt, make adjustments, and save
  </Step>
</Steps>

<Card href="/chat/creating-agents-from-chat">
  **Learn More** → Creating agents from chat sessions
</Card>

## What Happens After Creation?

Once you create an agent:

<Tabs>
  <Tab title="Test in Builder">
    Use the Builder to:

    * Test with sample inputs
    * Refine the system prompt
    * Verify tool usage
    * Check output format

    **Don't skip this step!** Testing before deploying prevents issues.
  </Tab>

  <Tab title="Set Up Triggers">
    Make your agent autonomous:

    * **Jira trigger** - Runs when tickets are created/updated
    * **Slack trigger** - Runs when mentioned in Slack
    * **Cron trigger** - Runs on a schedule
    * **Email trigger** - Runs when emails arrive

    <Card href="/agents/triggering-agents">View all trigger types</Card>
  </Tab>

  <Tab title="Monitor Performance">
    Track your agent's executions:

    * Success rate
    * Average duration
    * User feedback
    * Evaluation scores
  </Tab>

  <Tab title="Iterate & Improve">
    Agents improve over time:

    * Review failed executions
    * Incorporate user feedback
    * Use AI suggestions to refine prompts
    * A/B test different versions

    <Card href="/improving-agents/ai-suggested-improvements">Learn about optimization</Card>
  </Tab>
</Tabs>

## Common Patterns

### Pattern: Alert Enrichment Agent

```
Goal: Automatically enrich security alerts

Tools Needed:
- get_sentinelone_alert
- search_splunk
- virustotal_check_hash
- update_jira_ticket

Trigger: Jira issue created (type=Security Alert)

Prompt Focus:
- Extract indicators from alert
- Search for related activity
- Check threat intelligence
- Summarize findings in ticket
```

### Pattern: Scheduled Report Agent

```
Goal: Weekly access review report

Tools Needed:
- list_okta_users
- list_aws_iam_roles
- list_google_workspace_groups
- send_slack_message

Trigger: Cron (every Monday 9am)

Prompt Focus:
- Gather user/permission data
- Identify anomalies or stale accounts
- Generate formatted report
- Post to #security-reports
```

### Pattern: On-Demand Research Agent

```
Goal: Ad-hoc investigations via chat

Tools Needed:
- search_splunk
- list_sentinelone_alerts
- get_okta_user
- virustotal_*

Trigger: Chat (no automatic trigger)

Prompt Focus:
- Help analyst investigate indicators
- Provide context and enrichment
- Suggest next steps
- Generate summary reports
```

## Agent Configuration Options

When creating an agent, you can configure:

<AccordionGroup>
  <Accordion title="Model Selection" icon="brain">
    Choose which LLM powers your agent:

    * **General-purpose hosted model**: Strong reasoning, tool use, and instruction following
    * **High-speed/cost-optimized hosted model**: Good fit for simpler tasks or high volume
    * **Custom or self-hosted**: Bring your own fine-tuned or on-prem model
  </Accordion>

  <Accordion title="Planning Mode" icon="list-check">
    * **never**: Agent acts immediately (faster, 1-2 tool calls)
    * **auto**: Agent decides if planning helps (balanced)
    * **always**: Agent creates detailed plan first (complex multi-step tasks)

    **Tip**: Start with `auto`, adjust based on results
  </Accordion>

  <Accordion title="Tool Access" icon="toolbox">
    Grant only necessary tools. Over-granting tools:

    * Increases token usage (all tools described to LLM)
    * Can confuse the agent
    * Creates security risk

    **Best Practice**: Start minimal, add tools as needed
  </Accordion>

  <Accordion title="Skills" icon="copy">
    Skills let you attach reusable instructions and supporting files to multiple agents.

    Use them for:

    * Standard operating procedures
    * Shared report formats
    * Repeatable investigation workflows

    **Best Practice**: Put reusable workflow logic in skills, and keep the main system prompt focused on the agent's overall role.
  </Accordion>

  <Accordion title="Context Documents" icon="file-lines">
    Link up to 10 documents per agent. Documents are loaded into context at runtime.

    **Size Limits**:

    * 50KB per document (plain text equivalent)
    * Agent has \~200KB total context window

    **Tip**: Keep docs focused and concise
  </Accordion>

  <Accordion title="Evaluation Criteria" icon="star">
    Define how this agent should be evaluated:

    * Accuracy of findings
    * Completeness of investigation
    * Clarity of output
    * Appropriate tool usage

    Used for automated scoring and prompt optimization
  </Accordion>
</AccordionGroup>

## Tips for Success

<Note>
  **Start Small**: Create a focused agent that does one thing well. It's easier to expand scope than to debug an overly complex agent.
</Note>

<Note>
  **Test Extensively**: Use Builder to test many scenarios before deploying triggers. This catches issues early.
</Note>

<Note>
  **Monitor Early**: Check first 10-20 executions closely. This is when you'll discover prompt issues or missing tools.
</Note>

<Note>
  **Iterate Quickly**: Don't aim for perfection on first try. Deploy, observe, improve. Agents get better over time.
</Note>

## Troubleshooting Common Issues

<AccordionGroup>
  <Accordion title="Agent doesn't use the right tools">
    **Fix**: Make tool usage more explicit in system prompt:

    "Always start by calling `get_sentinelone_alert` to fetch full alert details"
  </Accordion>

  <Accordion title="Output format is inconsistent">
    **Fix**: Provide a template in the prompt:

    "Format your response exactly like this: \[template]"
  </Accordion>

  <Accordion title="Agent is too slow">
    **Fix**:

    * Reduce number of granted tools
    * Set planning mode to `never`
    * Remove verbose context documents
    * Check if tools themselves are slow (API performance)
  </Accordion>

  <Accordion title="Agent makes wrong decisions">
    **Fix**:

    * Add decision criteria to prompt
    * Provide examples of good/bad decisions
    * Check if context documents have necessary info
    * Verify tool outputs are correct
  </Accordion>
</AccordionGroup>