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

# Analysis Agent

> Run a data analysis agent on a Relace Repo

## Path Parameters

<ParamField path="repo_id" type="string" required>
  Repo ID
</ParamField>

## Request Body

<ParamField body="agent_name" type="string" required>
  Name of the predefined agent to run
</ParamField>

<ParamField body="agent_inputs" type="object" required>
  Input parameters for the agent

  <Expandable title="properties" defaultOpen={false}>
    <ParamField body="query" type="string" required>
      The query or question to process with the agent
    </ParamField>

    <ParamField body="system_prompt" type="string">
      Custom system prompt to guide the agent's behavior
    </ParamField>
  </Expandable>
</ParamField>

## Response

The agent returns a **Server-Sent Events (SSE) stream** with real-time updates from tool calls. The various event types indicate different stages of execution.

### Event Types

<ResponseField name="started" type="event">
  Signals that the agent execution has begun

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="prompt_id" type="string">
      Unique identifier for this agent execution session
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="agent" type="event">
  Contains agent reasoning, analysis, and text responses

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="content" type="string">
      The agent's response content or reasoning
    </ResponseField>

    <ResponseField name="type" type="string">
      Type of agent message (e.g., "reasoning", "response")
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tool" type="event">
  Reports tool usage and execution results

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="tool_name" type="string">
      Name of the tool being used
    </ResponseField>

    <ResponseField name="content" type="string">
      Tool execution details or results
    </ResponseField>

    <ResponseField name="status" type="string">
      Tool execution status (e.g., "started", "completed")
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="committed" type="event">
  Indicates code changes have been made to the repository

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="files" type="array">
      List of files that were modified
    </ResponseField>

    <ResponseField name="message" type="string">
      Commit message describing the changes
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="build" type="event">
  Reports build process status and results

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="event" type="string">
      Build event type: "start", "pass", or "fail"
    </ResponseField>

    <ResponseField name="output" type="string">
      Build output or error messages
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="test" type="event">
  Reports test execution status and results

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="event" type="string">
      Test event type: "start", "pass", or "fail"
    </ResponseField>

    <ResponseField name="output" type="string">
      Test output or results
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="deployed" type="event">
  Signals that changes have been deployed/visualizations updated

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="status" type="string">
      Deployment status
    </ResponseField>

    <ResponseField name="url" type="string">
      URL to view the deployed changes
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="prompt_error" type="event">
  Reports errors that occurred during agent execution

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="error" type="string">
      Error message describing what went wrong
    </ResponseField>

    <ResponseField name="code" type="string">
      Error code for programmatic handling
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="done" type="event">
  Signals that the agent execution has completed successfully

  <Expandable title="properties" defaultOpen={false}>
    <ResponseField name="summary" type="string">
      Summary of what was accomplished
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.relace.run/v1/repo/123e4567-e89b-12d3-a456-426614174000/agent \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_name": "code-analyzer",
      "agent_inputs": {
        "query": "Analyze user engagement data and create visualization plots",
        "system_prompt": "Generate comprehensive data analysis with matplotlib/plotly visualizations"
      },
      "overrides": {}
    }'
  ```

  ```python Python theme={null}
  import requests
  import json

  repo_id = "123e4567-e89b-12d3-a456-426614174000"
  url = f"https://api.relace.run/v1/repo/{repo_id}/agent"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "agent_name": "analysis-agent",
      "agent_inputs": {
          "query": "Analyze user engagement data and create visualization plots",
          "system_prompt": "Generate comprehensive data analysis with matplotlib/plotly visualizations"
      },
      "overrides": {}
  }

  response = requests.post(url, headers=headers, json=data)
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```text SSE Stream theme={null}
  event: started
  data: {"prompt_id": "prompt_123e4567-e89b-12d3-a456-426614174000"}

  event: agent
  data: {"content": "I'll analyze the user engagement data and create visualization plots.", "type": "reasoning"}

  event: tool
  data: {"tool_name": "data_analyzer", "content": "Loading dataset with 10,000 records", "status": "started"}

  event: tool
  data: {"tool_name": "data_analyzer", "content": "Analysis complete. Found key patterns in engagement data.", "status": "completed"}

  event: agent
  data: {"content": "Analysis shows 65% higher engagement on weekends with peak activity between 2-4 PM.", "type": "response"}

  event: tool
  data: {"tool_name": "plot_generator", "content": "Generating engagement trend visualization", "status": "started"}

  event: committed
  data: {"files": ["plots/engagement_trends.png", "analysis/engagement_report.md"], "message": "Add engagement analysis and visualization plots"}

  event: build
  data: {"event": "start", "output": "Building visualization components..."}

  event: build
  data: {"event": "pass", "output": "Build completed successfully"}

  event: deployed
  data: {"status": "success", "url": "https://app.relace.ai/repo/123e4567/viz"}

  event: done
  data: {"summary": "Successfully analyzed engagement data and generated 2 visualization plots"}
  ```
</ResponseExample>