Analytics

Experimental Feature

The Analytics tool is currently experimental. Functionality, endpoints, and behavior may change in future releases.

Tool Agents can execute code in a secure sandbox using the Analytics tool. This enables advanced data analysis, visualization generation, and programmatic processing of uploaded files. The agent writes and runs Python code on your behalf, returning text results and optionally generating downloadable artifacts such as charts and transformed datasets.

Analytics can be available on either:

• The top-level Tool Agent, which can analyze the file directly.
• A Task Agent configured as one of the top-level agent's tools, which can perform the analysis after delegation.
• Both agents, allowing the top-level model to choose whether to analyze directly or delegate.

The top-level agent does not need its own analytics tool when an eligible Task Agent tool has analytics.

Agent Configuration

The agent must be configured with the analytics tool. No additional tool configuration is required:

{
  "name": "data-analyst",
  "displayName": "Data Analyst",
  "description": "An agent that analyzes data and generates visualizations",
  "agentType": "tool",
  "config": {
    "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
    "systemPrompt": "You are a data analysis assistant. Use the analytics tools to analyze uploaded files, generate visualizations, and provide statistical insights.",
    "tools": [
      {
        "toolType": "analytics"
      }
    ]
  }
}

The analytics tool does not require name or description. It does not accept argumentPolicy; supplying one returns 400 Bad Request.

Workflow

The workflow depends on where the data comes from:

1. Provide the data — Upload a local file through the File Management API, or configure a tool such as semantic_search to retrieve data during the invocation.
2. Invoke the agent — Describe the analysis and include the file_analysis reference if using an uploaded file.
3. Use the results — Read the text response and download any generated artifacts.

Optional: Upload a Local Data File

Skip this section when the agent will retrieve data through semantic_search or another tool.

First, request a presigned upload URL through the POST /v1/files endpoint:

curl -X POST "/v1/files" \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "sales_data.csv",
    "mediaType": "text/csv",
    "sizeBytes": 1024,
    "accessScope": { "type": "user" }
  }'

Parameter	Description	Required
fileName	Name of the file, such as sales_data.csv	Yes
mediaType	MIME type; must be a supported type	Yes
sizeBytes	Size of the file in bytes (maximum 100 MB)	Yes
accessScope	Access scope with type "user" for private files (default) or "tenant" for organization-wide sharing	No

The response supplies the file reference and presigned upload URL:

{
  "fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fileName": "sales_data.csv",
  "sizeBytes": 1024,
  "createdAt": "2026-03-09T12:00:00Z",
  "uploadUrl": "https://code-interpreter-bucket.s3.amazonaws.com/...",
  "uploadExpiresAt": "2026-03-09T13:00:00Z"
}

Save the fileId for the agent invocation and use the uploadUrl to upload the file:

curl -X PUT "https://code-interpreter-bucket.s3.amazonaws.com/..." \
  -H "Content-Type: text/csv" \
  -H "Content-Length: <sizeBytes>" \
  --data-binary @sales_data.csv

Both Content-Type and Content-Length are signed into the URL, so they must match the values declared when the upload session was created. A successful upload returns HTTP 200 with no body.

warning

Presigned upload URLs expire after 1 hour. If the URL expires, request a new one through POST /v1/files.

warning

Uploaded files are automatically deleted after 24 hours according to the S3 bucket's lifecycle policy. Upload the file again to analyze it after that period.

Invoke the Agent

Send your analysis request to the agent, referencing the uploaded file by its fileId:

curl -X POST "/v1/agents/{agent_id}/versions/{version_id}/invoke" \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Analyze the sales data and create a bar chart showing total sales by category. Include summary statistics."
          },
          {
            "type": "file_analysis",
            "fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "fileName": "sales_data.csv",
            "mediaType": "text/csv"
          }
        ]
      }
    ]
  }'

The message content array contains two parts:

Field	Description
type: "text"	Your natural language analysis request
type: "file_analysis"	Reference to the uploaded file; requires fileId, fileName, and mediaType

The runtime provides the canonical file reference to the analytics-capable agent, which imports the file into its sandbox before running code. You do not need to provide a download URL.

Use file_analysis instead of embedding file information only in free-form prompt text. All three fields (fileId, fileName, and mediaType) identify the file and are required.

Invoke with Content Lake Data

If the agent is configured to search Content Lake, the request only needs to describe what information to find and how to analyze it:

curl -X POST "/v1/agents/{agent_id}/versions/{version_id}/invoke" \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Search the policy documents for claim-resolution targets, compare the targets by policy, and create a bar chart."
      }
    ]
  }'

No file reference is needed. The agent finds the relevant Content Lake information, prepares it in a secure analysis workspace, and performs the requested analysis.

Depending on your prompt, the agent may:

• Generate artifacts such as charts or transformed files, returned as downloadable URLs.
• Return text-only results such as answers, summary statistics, or descriptions of patterns.

Download Results

When the agent generates artifacts, the response includes download URLs. Text-only analysis does not create or require an artifact. Artifact URLs are preserved when analytics runs directly or through a Task Agent tool, for both streaming and non-streaming invocations.

{
  "output": [
    {
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Here is the analysis:\n\nStatistical Summary:\n- Total Sales: $1,000.00\n- Average: $200.00\n- Max: $300.00\n- Min: $100.00\n\nArtifacts:\n- https://artifacts.agents.ai.app.hyland.com/account/env/artifacts/chart-uuid-filename.png"
        }
      ]
    }
  ]
}

Download an artifact using its URL:

curl "https://artifacts.agents.ai.app.hyland.com/account/env/artifacts/chart-uuid-filename.png" -o sales_chart.png

warning

Generated artifacts are stored in S3 with a 1-day lifecycle policy. Download artifacts within 24 hours or rerun the analysis to generate new ones.

Supported Data Formats

The following file types can be uploaded through the /v1/files endpoint:

Format	MIME Type
Plain Text	text/plain
CSV	text/csv
TSV	text/tab-separated-values
HTML	text/html
Markdown	text/markdown
XML	text/xml, application/xml
JSON	application/json
Excel	application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

caution

This feature is experimental. The list of supported MIME types may change as the functionality is finalized.

Combining Analytics with Semantic Search

The semantic_search tool can be configured alongside analytics when the agent must retrieve Content Lake data and then perform calculations, comparisons, or visualizations over the results:

{
  "name": "knowledge-data-analyst",
  "displayName": "Knowledge Data Analyst",
  "description": "Retrieves Content Lake information and analyzes the results.",
  "agentType": "tool",
  "config": {
    "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
    "systemPrompt": "Use semantic_search to retrieve relevant information. Before analyzing retrieved data with analytics tools, write it to the sandbox with import_data_to_sandbox and reuse the returned session_id for subsequent tool calls.",
    "tools": [
      {
        "toolType": "rag",
        "name": "semantic_search",
        "description": "Search Content Lake for relevant document content.",
        "funcName": "semantic_search",
        "semanticSearchConfig": {
          "hxqlQuery": "SELECT * FROM SysContent WHERE documentType = 'Policy'",
          "hybridSearch": true,
          "limit": 20
        }
      },
      {
        "toolType": "analytics"
      }
    ]
  }
}

For example, a user can ask:

Search the policy documents for stated claim-resolution targets, compare the targets by policy, and create a bar chart.

The agent handles the workflow for you:

1. Uses the semantic_search tool to find the relevant information in the configured Content Lake documents.
2. Automatically imports the search results into a secure sandbox.
3. Uses Analytics to compare the policy targets and generate any requested charts.
4. Returns the analysis and downloadable links to any generated charts.

You do not need to upload a file or include file_analysis when the data comes from semantic_search. A file reference is only required when you upload a local file for analysis.

Delegating Analytics to a Task Agent

Reference an analytics-capable Task Agent with toolType: "task_agent". Give the tool a useful description so the top-level model can decide when to delegate:

{
  "name": "delegating-data-assistant",
  "displayName": "Delegating Data Assistant",
  "description": "Delegates data-analysis requests to a specialized agent.",
  "agentType": "tool",
  "config": {
    "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
    "systemPrompt": "You are a helpful assistant. Use the available tools or delegate tasks when appropriate.",
    "tools": [
      {
        "toolType": "task_agent",
        "agentId": "a51fbe06-8eaa-4548-b72c-359e8589f522",
        "agentVersion": "latest",
        "description": "Handles delegated data analysis and file-processing tasks."
      }
    ]
  }
}

When the request contains file_analysis, the runtime supplies the exact file reference to the top-level model. If it delegates, the model passes the relevant reference to the analytics-capable Task Agent invocation. The child imports the file into its own sandbox before analysis.

If neither the top-level agent nor an eligible Task Agent tool has analytics, the invocation returns 400 Bad Request instead of asking a model that cannot access the file to process it.

Using Analytics Directly in a Task Agent

A Task Agent can combine structured inputs with uploaded files supplied through messages. Configure the Task Agent with an analytics tool:

{
  "name": "sales-data-analyzer",
  "displayName": "Sales Data Analyzer",
  "description": "Analyzes uploaded sales data with configurable visualization",
  "agentType": "task",
  "config": {
    "llmModelId": "anthropic.claude-haiku-4-5-20251001-v1:0",
    "systemPrompt": "Analyze the uploaded data file. Create a {{visualization_type}} chart showing the key trends. Include summary statistics.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "visualization_type": {
          "type": "string",
          "description": "Type of chart to generate (for example, bar, line, or pie)"
        }
      },
      "required": ["visualization_type"]
    },
    "tools": [
      {
        "toolType": "analytics"
      }
    ],
    "inferenceConfig": {
      "maxTokens": 4000,
      "temperature": 0.1
    }
  }
}

Provide the template variables in inputs and the uploaded file reference in messages:

{
  "inputs": {
    "visualization_type": "bar"
  },
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "file_analysis",
          "fileId": "12345678-1234-1234-1234-1234567890ab",
          "fileName": "quarterly_sales.csv",
          "mediaType": "text/csv"
        }
      ]
    }
  ]
}

Best Practices for Analytics

• Be specific in analysis requests and clearly describe the desired chart, columns, or metrics.
• Use descriptive filenames such as sales_q1_2026.csv.
• Download artifacts promptly because generated files expire.
• Break complex analyses into steps for large or multi-part requests.
• Verify the file format and ensure mediaType matches the actual file.