> ## 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.

# Agent Outputs

> Define structured JSON schemas for consistent agent output

**Agent outputs** let you define a JSON schema that your agent returns at the end of every run. This ensures consistent output that can be displayed visually for easy verification, integrated with downstream systems, or used for reporting.

## What Are Agent Outputs?

Instead of relying on freeform text responses, agent outputs enforce a specific structured data format:

<CardGroup cols={2}>
  <Card title="Consistent Format" icon="layer-group">
    Every run produces the same shape of data, making it easy to verify outcomes, compare results, and build reports.
  </Card>

  <Card title="Rich Visualization" icon="eye">
    Output is rendered with markdown formatting, classification badges, and organized sections—not raw JSON.
  </Card>

  <Card title="Template Library" icon="sparkles">
    Start with pre-built templates for investigations, reports, enrichments, and more.
  </Card>

  <Card title="AI-Powered Generation" icon="wand-magic-sparkles">
    Generate a schema automatically from your agent's system prompt.
  </Card>
</CardGroup>

<Note>
  Agent outputs are **in addition to** the standard run timeline. You can always view the full execution history, tool calls, and agent reasoning alongside the structured output.
</Note>

## When to Use Agent Outputs

<AccordionGroup>
  <Accordion title="Use Agent Outputs When..." icon="check">
    * You need consistent, parseable output from every run
    * You want classification labels (True Positive, False Positive, etc.)
    * Output includes formatted reports with multiple sections
    * You want to surface evidence behind agent decisions in an easier-to-read format
    * Results will be displayed in a UI or dashboard
    * Results will be aggregated for reporting
  </Accordion>

  <Accordion title="Skip Agent Outputs When..." icon="xmark">
    * Agent output is conversational (e.g., Slack assistant)
    * Every run produces fundamentally different types of output
    * You don't need to parse or store the results
  </Accordion>
</AccordionGroup>

## Getting Started

### Enabling Agent Outputs

<Steps>
  <Step title="Open Agent Configuration">
    Navigate to your agent's configuration page and scroll to **Agent Output Schema**
  </Step>

  <Step title="Enable the Feature">
    Toggle the schema to **Enabled**
  </Step>

  <Step title="Choose a Starting Point">
    Select from:

    * **Generate Schema**: AI analyzes your system prompt and creates a relevant schema
    * **Template**: Start with a pre-built template for common use cases
    * **Blank**: Build from scratch with full control
  </Step>

  <Step title="Customize and Preview">
    Edit the schema to match your needs and preview how output will look
  </Step>

  <Step title="Save and Test">
    Save your agent and observe structured outputs for all future runs
  </Step>
</Steps>

## Templates

Templates provide pre-built schemas for common agent patterns. They're great starting points that can either be used as-is or easily customized:

<Tabs>
  <Tab title="Investigator">
    **Best for**: Alert triage, threat hunting, incident analysis

    Includes:

    * **Classification**: True Positive / False Positive verdict
    * **Confidence**: High / Medium / Low confidence level
    * **Report**: Structured sections for summary, evidence, and next steps

    ```json theme={null}
    {
      "classification": "True Positive",
      "confidence": "High",
      "report": {
        "summary": "Executive summary of findings",
        "evidence": "Key evidence and artifacts",
        "nextSteps": "Recommended actions"
      }
    }
    ```
  </Tab>

  <Tab title="Report">
    **Best for**: Simple reports, summaries, documentation

    Includes:

    * **Report**: Single markdown-formatted report field

    ```json theme={null}
    {
      "report": "# Summary\n\nMarkdown-formatted report content..."
    }
    ```
  </Tab>

  <Tab title="Templated Report">
    **Best for**: Structured investigations with multiple sections

    Includes:

    * **Report object** with:
      * Summary section
      * Evidence section
      * Next steps section

    ```json theme={null}
    {
      "report": {
        "summary": "High-level overview",
        "evidence": "Detailed evidence and findings",
        "nextSteps": "Recommended remediation"
      }
    }
    ```
  </Tab>

  <Tab title="Rule Evaluator">
    **Best for**: Detection rule validation, rule tuning

    Includes:

    * **Classification**: Evaluation verdict
    * **Report**: Analysis and reasoning

    ```json theme={null}
    {
      "classification": "False Positive",
      "report": "Analysis of why this detection fired..."
    }
    ```
  </Tab>

  <Tab title="Helper / Slack Bot">
    **Best for**: Assistant agents, Slack bots, chat-based agents

    Includes:

    * **Steps Taken**: Array of actions performed

    ```json theme={null}
    {
      "stepsTaken": [
        "Looked up user in Okta",
        "Checked recent login activity",
        "Verified no anomalies detected"
      ]
    }
    ```
  </Tab>

  <Tab title="Enrichment">
    **Best for**: Indicator enrichment, threat intelligence

    Includes:

    * **Report**: Markdown report of enrichment findings

    ```json theme={null}
    {
      "report": "# Enrichment Results\n\n**IP**: 8.8.8.8\n**Reputation**: Clean..."
    }
    ```
  </Tab>

  <Tab title="Orchestrator">
    **Best for**: Multi-step workflows, automation agents

    Includes:

    * **Steps Taken**: Log of orchestration actions

    ```json theme={null}
    {
      "stepsTaken": [
        "Triggered downstream agent A",
        "Updated Jira ticket",
        "Posted notification to Slack"
      ]
    }
    ```
  </Tab>
</Tabs>

## Schema Building

### Available Types

The schema builder supports standard JSON types:

| Type    | Icon | Description                    |
| ------- | ---- | ------------------------------ |
| Object  | `{}` | Container for named properties |
| Array   | `[]` | List of items                  |
| String  | `T`  | Text values                    |
| Number  | `#`  | Numeric values                 |
| Boolean | `◎`  | True/false values              |
| Null    | `∅`  | Null/empty value               |

### Presets

Presets are special field configurations with built-in rendering:

<AccordionGroup>
  <Accordion title="Classification" icon="tags">
    A string field with predefined enum values for categorization.

    **Default values**: "True Positive", "False Positive"

    **Rendered as**: Styled badge/chip

    **Use for**: Verdicts, severity levels, status values

    ```json theme={null}
    {
      "classification": "True Positive"
    }
    ```
  </Accordion>

  <Accordion title="Markdown" icon="file-lines">
    A string field rendered with full markdown formatting.

    **Supports**: Headings, lists, tables, code blocks, bold/italic, links

    **Use for**: Reports, summaries, detailed analysis

    ```json theme={null}
    {
      "report": "# Investigation Summary\n\nThis is a **critical** finding..."
    }
    ```
  </Accordion>

  <Accordion title="Templated Report" icon="rectangle-list">
    An object with predefined sections: summary, evidence, and next steps.

    **Structure**:

    * Summary (markdown)
    * Evidence (markdown)
    * Next Steps (markdown)

    **Use for**: Structured investigation reports

    ```json theme={null}
    {
      "report": {
        "summary": "# Summary\n...",
        "evidence": "## Evidence\n...",
        "nextSteps": "## Recommendations\n..."
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Enum Values

For string fields, you can restrict values to a predefined list:

<Steps>
  <Step title="Create String Field">
    Add a new string field to your schema
  </Step>

  <Step title="Enable Enum">
    Click the options menu (⋮) and select "Restrict to enum values"
  </Step>

  <Step title="Add Values">
    Type values separated by commas or press Enter after each value
  </Step>
</Steps>

**Example enum values**:

* Severity: `Critical, High, Medium, Low, Info`
* Status: `Open, In Progress, Resolved, Closed`
* Confidence: `High, Medium, Low`

### Required vs Optional Fields

By default, all fields are **required**. To make a field optional:

1. Click the options menu (⋮) next to the field
2. Select "Optional"

Optional fields can be omitted or set to null in the output.

## Schema Generation

If you have a system prompt written, you can generate a schema tailored to your task automatically:

<Steps>
  <Step title="Write System Prompt First">
    Ensure your agent has a clear system prompt describing what it does
  </Step>

  <Step title="Click Generate Schema">
    In the schema builder, click "Generate Schema"
  </Step>

  <Step title="Review Generated Schema">
    AI analyzes your prompt and creates a relevant schema with:

    * Appropriate fields for your use case
    * Sensible presets (markdown, classification, etc.)
    * Semantically relevant example output preview
  </Step>

  <Step title="Customize">
    Modify the generated schema as needed
  </Step>
</Steps>

<Note>
  Schema generation requires a system prompt. If your agent doesn't have one yet, write it first before generating a schema.
</Note>

## Viewing Agent Output

When an agent run completes, the structured output is displayed in two ways:

<Tabs>
  <Tab title="Visual View">
    The default view renders output with rich formatting:

    * **Classifications** appear as styled badges
    * **Markdown** is rendered with headings, lists, code blocks
    * **Numbers** display prominently with labels
    * **Nested objects** show as organized sections
    * **Arrays** render as lists or grids

    This view is designed for human consumption.
  </Tab>

  <Tab title="JSON View">
    Toggle to JSON view to see the raw data structure:

    * Exact JSON payload returned by the agent
    * Copy button for easy export
    * Schema reference alongside the data

    This view is useful for debugging or integration.
  </Tab>
</Tabs>

## Real-World Examples

### Example 1: Alert Triage Agent

**Use case**: Automatically triage SentinelOne alerts

**Schema** (using Investigator template):

```json theme={null}
{
  "type": "object",
  "properties": {
    "classification": {
      "type": "string",
      "enum": ["True Positive", "False Positive", "Suspicious", "Inconclusive"],
      "description": "Verdict for this alert"
    },
    "confidence": {
      "type": "string",
      "enum": ["High", "Medium", "Low"],
      "description": "Confidence in the classification"
    },
    "severity": {
      "type": "string",
      "enum": ["Critical", "High", "Medium", "Low"],
      "description": "Assessed severity if true positive"
    },
    "report": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string",
          "description": "Executive summary of findings"
        },
        "evidence": {
          "type": "string",
          "description": "Key evidence supporting the classification"
        },
        "nextSteps": {
          "type": "string",
          "description": "Recommended actions for the analyst"
        }
      }
    }
  }
}
```

**Example output**:

```json theme={null}
{
  "classification": "True Positive",
  "confidence": "High",
  "severity": "Critical",
  "report": {
    "summary": "Confirmed ransomware execution on endpoint WORKSTATION-42...",
    "evidence": "- File hash matches known LockBit variant\n- Encryption behavior observed\n- Ransom note dropped in multiple directories",
    "nextSteps": "1. Isolate endpoint immediately\n2. Page on-call security\n3. Preserve forensic evidence"
  }
}
```

### Example 2: Weekly Report Agent

**Use case**: Generate weekly security metrics

**Schema** (custom):

```json theme={null}
{
  "type": "object",
  "properties": {
    "reportDate": {
      "type": "string",
      "description": "Date range for this report"
    },
    "alertsTotal": {
      "type": "number",
      "description": "Total alerts in period"
    },
    "truePositives": {
      "type": "number",
      "description": "Confirmed true positives"
    },
    "falsePositives": {
      "type": "number",
      "description": "Confirmed false positives"
    },
    "report": {
      "type": "string",
      "description": "Detailed markdown report"
    }
  }
}
```

**Example output**:

```json theme={null}
{
  "reportDate": "2025-01-08 to 2025-01-15",
  "alertsTotal": 247,
  "truePositives": 12,
  "falsePositives": 198,
  "report": "# Weekly Security Report\n\n## Key Metrics\n- **Total Alerts**: 247\n- **True Positive Rate**: 4.9%\n- **MTTD**: 12 minutes\n\n## Notable Incidents\n..."
}
```

## Schema Builder Reference

### Field Options

Each field supports these options:

| Option          | Description                                                |
| --------------- | ---------------------------------------------------------- |
| **Type**        | Data type (string, number, boolean, object, array, null)   |
| **Name**        | Property name in JSON (alphanumeric, hyphens, underscores) |
| **Description** | Guides the LLM on what to put in this field                |
| **Required**    | Whether the field must be present (default: yes)           |
| **Enum**        | For strings, restrict to specific values                   |
| **Preset**      | Apply special rendering (classification, markdown, etc.)   |

### Property Name Rules

Property names must:

* Contain only letters, numbers, hyphens, and underscores
* Be unique within their parent object

**Valid**: `classification`, `risk-score`, `next_steps`, `reportV2`

**Invalid**: `my field` (spaces), `report@v2` (special characters)

<Tip>
  **Hyphenated names render nicely**: Property names with hyphens are automatically formatted for display. For example, `executive-summary` renders as **Executive Summary** in the visual output view.
</Tip>