Account Research Brief

The Account Research Brief agent generates comprehensive sales enablement briefs for target accounts. It orchestrates multiple Phoenix MCP tools to gather firmographic, technographic, spend, and contact data, then synthesizes everything into a polished HTML brief.

Overview

Agent ID: account-research

Output: Self-contained HTML document with company insights, technology stack, spending analysis, key contacts, and actionable recommendations.

Execution Time: 2-5 minutes depending on depth setting

Quick Start

1. Start a Research Run

curl -X POST "https://phoenix.hginsights.com/api/agents/v1/agents/account-research/runs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "domain": "salesforce.com"
    },
    "params": {
      "depth": "standard",
      "output_formats": ["html"]
    }
  }'

Response:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

2. Poll for Completion

curl "https://phoenix.hginsights.com/api/agents/v1/runs/{run_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (in progress):

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "progress": 0.45,
  "started_at": "2024-01-26T10:00:00Z"
}

Response (completed):

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "succeeded",
  "progress": 1.0,
  "cost_summary": {
    "tool_credits": 5.0,
    "llm_credits": 2.5,
    "total_credits": 7.5
  },
  "started_at": "2024-01-26T10:00:00Z",
  "finished_at": "2024-01-26T10:03:45Z"
}

3. Retrieve the Brief

curl "https://phoenix.hginsights.com/api/agents/v1/runs/{run_id}/artifacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "artifacts": [
    {
      "id": "artifact-uuid",
      "artifact_type": "html",
      "url": "/v1/runs/550e8400-e29b-41d4-a716-446655440000/artifacts/brief.html",
      "created_at": "2024-01-26T10:03:45Z"
    }
  ]
}

Input Parameters

Required: Company Identifier

Provide one of the following:

Field	Type	Description
`domain`	string	Company website domain (e.g., "salesforce.com")
`hgid`	string	HG Insights company ID

Optional: Research Parameters

Field	Type	Default	Description
`depth`	string	`"standard"`	Research depth: `quick`, `standard`, or `deep`
`output_formats`	array	`["html"]`	Output formats: `html`, `markdown`, `pdf`

Optional: Tool Selection

Control which data sources to include:

{
  "tool_selection": {
    "company_firmographic": true,
    "company_technographic": true,
    "company_spend": true,
    "company_cloud_spend": true,
    "company_fai": true,
    "company_contracts": false,
    "contact_search": true,
    "contact_enrich": true,
    "sec_filing_section": true,
    "sec_full_text_search": false,
    "web_search": true
  }
}

Research Depth Levels

Quick (1-2 minutes)

Single-page executive summary with:

Company overview and firmographics
Top 5-10 technologies
Key contacts

Best for: Quick prospect qualification, meeting prep with time constraints.

Standard (2-4 minutes)

Comprehensive brief including:

Full firmographic profile
Complete technology stack analysis
IT and cloud spending breakdown
Key stakeholder identification
SEC filing insights (public companies)
Recent news and web search results

Best for: Sales call preparation, account planning, opportunity research.

Deep (4-8 minutes)

In-depth research with:

Everything in Standard, plus:
Competitive technology analysis
Contract intelligence
Full contact enrichment
Extended SEC filing analysis
Comprehensive web research

Best for: Strategic accounts, executive briefings, RFP preparation.

Run Statuses

Status	Description
`queued`	Run accepted, waiting to start
`running`	Agent is executing
`succeeded`	Completed successfully, artifacts available
`partially_failed`	Completed with some tool failures
`failed`	Execution failed

Investigating Failures

Get Execution Trace

curl "https://phoenix.hginsights.com/api/agents/v1/runs/{run_id}/trace" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "steps": [
    {
      "step_number": 1,
      "tool_name": "company_firmographic",
      "status": "success",
      "duration_ms": 1250,
      "input": {"companyDomain": "salesforce.com"},
      "output_summary": "Found company: Salesforce Inc."
    },
    {
      "step_number": 2,
      "tool_name": "company_technographic",
      "status": "success",
      "duration_ms": 2340,
      "input": {"companyDomain": "salesforce.com"},
      "output_summary": "Found 156 technologies"
    }
  ],
  "model_usage": {
    "provider": "openrouter",
    "model": "anthropic/claude-3.5-sonnet",
    "total_tokens": 15000,
    "cost_usd": 0.045
  },
  "total_duration_ms": 185000
}

Debug Endpoint (Development)

curl "https://phoenix.hginsights.com/api/agents/v1/runs/{run_id}/debug" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns full execution details including raw tool inputs/outputs.

Example: Python Integration

import requests
import time

API_KEY = "phx_your_api_key_here"
BASE_URL = "https://phoenix.hginsights.com/api/agents"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def generate_account_brief(domain: str, depth: str = "standard") -> str:
    """Generate an account research brief and return the artifact URL."""

    # 1. Start the run
    response = requests.post(
        f"{BASE_URL}/v1/agents/account-research/runs",
        headers=headers,
        json={
            "input": {"domain": domain},
            "params": {"depth": depth, "output_formats": ["html"]}
        }
    )
    response.raise_for_status()
    run_id = response.json()["run_id"]
    print(f"Started run: {run_id}")

    # 2. Poll for completion
    while True:
        status_response = requests.get(
            f"{BASE_URL}/v1/runs/{run_id}",
            headers=headers
        )
        status_response.raise_for_status()
        status = status_response.json()

        print(f"Status: {status['status']}, Progress: {status.get('progress', 0):.0%}")

        if status["status"] == "succeeded":
            break
        elif status["status"] == "failed":
            raise Exception(f"Run failed: {status.get('error')}")

        time.sleep(5)  # Poll every 5 seconds

    # 3. Get artifacts
    artifacts_response = requests.get(
        f"{BASE_URL}/v1/runs/{run_id}/artifacts",
        headers=headers
    )
    artifacts_response.raise_for_status()
    artifacts = artifacts_response.json()["artifacts"]

    # Return the HTML artifact URL
    html_artifact = next(a for a in artifacts if a["artifact_type"] == "html")
    return html_artifact["url"]


# Usage
brief_url = generate_account_brief("salesforce.com", depth="standard")
print(f"Brief available at: {brief_url}")

Example: JavaScript/TypeScript Integration

const API_KEY = "phx_your_api_key_here";
const BASE_URL = "https://phoenix.hginsights.com/api/agents";

const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json"
};

interface RunResponse {
  run_id: string;
  status: "queued" | "running" | "succeeded" | "partially_failed" | "failed";
  progress?: number;
  error?: string;
}

interface ArtifactsResponse {
  artifacts: Array<{
    id: string;
    artifact_type: string;
    url: string;
    created_at: string;
  }>;
}

async function generateAccountBrief(
  domain: string,
  depth: "quick" | "standard" | "deep" = "standard"
): Promise<string> {
  // 1. Start the run
  const startResponse = await fetch(
    `${BASE_URL}/v1/agents/account-research/runs`,
    {
      method: "POST",
      headers,
      body: JSON.stringify({
        input: { domain },
        params: { depth, output_formats: ["html"] },
      }),
    }
  );

  if (!startResponse.ok) {
    throw new Error(`Failed to start run: ${startResponse.statusText}`);
  }

  const { run_id } = await startResponse.json();
  console.log(`Started run: ${run_id}`);

  // 2. Poll for completion
  while (true) {
    const statusResponse = await fetch(
      `${BASE_URL}/v1/runs/${run_id}`,
      { headers }
    );
    const status: RunResponse = await statusResponse.json();

    console.log(`Status: ${status.status}, Progress: ${(status.progress ?? 0) * 100}%`);

    if (status.status === "succeeded") {
      break;
    } else if (status.status === "failed") {
      throw new Error(`Run failed: ${status.error}`);
    }

    await new Promise((resolve) => setTimeout(resolve, 5000)); // Poll every 5 seconds
  }

  // 3. Get artifacts
  const artifactsResponse = await fetch(
    `${BASE_URL}/v1/runs/${run_id}/artifacts`,
    { headers }
  );
  const { artifacts }: ArtifactsResponse = await artifactsResponse.json();

  const htmlArtifact = artifacts.find((a) => a.artifact_type === "html");
  if (!htmlArtifact) {
    throw new Error("No HTML artifact found");
  }

  return htmlArtifact.url;
}

// Usage
const briefUrl = await generateAccountBrief("salesforce.com", "standard");
console.log(`Brief available at: ${briefUrl}`);

Brief Contents

The generated HTML brief includes:

Executive Summary

Company overview and key facts
Industry and market position
Recent news highlights

Firmographic Profile

Headquarters, employee count, revenue
Industry classification
Subsidiary and parent company relationships

Technology Stack

Current technology installations by category
Technology spend indicators
Recent technology changes

Spending Analysis

Total IT spend estimates
Cloud vendor breakdown (AWS, Azure, GCP)
Spend by category

Key Contacts

Decision makers by function
Contact information (when available)
Organizational structure insights

Recommendations

Talking points for sales conversations
Potential pain points and opportunities
Suggested next steps

Customization

Tenant Branding

Contact your Phoenix administrator to configure:

Custom logo in generated briefs
Brand colors and styling
Footer text and disclaimers

Output Templates

The default output is an HG Insights-branded HTML brief. Custom templates may be available for enterprise accounts.

Troubleshooting

Run Stuck in "queued" Status

The agent service may be at capacity. Runs are processed in order. If a run remains queued for more than 5 minutes, contact support.

"partially_failed" Status

Some tools failed but the brief was still generated. Check the trace to see which tools failed:

curl "https://phoenix.hginsights.com/api/agents/v1/runs/{run_id}/trace" \
  -H "Authorization: Bearer YOUR_API_KEY"

Common causes:

Company not found in HG Insights database
Rate limiting on external data sources
Network timeouts

Empty Brief Sections

If certain sections are empty:

The company may not have data in that category
The tool may have failed (check trace)
Tool selection may have excluded that data source

Rate Limits

Concurrent runs: 10 per organization (default)
API calls: 100 requests/minute per organization

Contact your account manager to adjust limits.

Next Steps

API Reference - Complete endpoint documentation
Examples - More workflow examples

Overview​

Quick Start​

1. Start a Research Run​

2. Poll for Completion​

3. Retrieve the Brief​

Input Parameters​

Required: Company Identifier​

Optional: Research Parameters​

Optional: Tool Selection​

Research Depth Levels​

Quick (1-2 minutes)​

Standard (2-4 minutes)​

Deep (4-8 minutes)​

Run Statuses​

Investigating Failures​

Get Execution Trace​

Debug Endpoint (Development)​

Example: Python Integration​

Example: JavaScript/TypeScript Integration​

Brief Contents​

Executive Summary​

Firmographic Profile​

Technology Stack​

Spending Analysis​

Key Contacts​

Recommendations​

Customization​

Tenant Branding​

Output Templates​

Troubleshooting​

Run Stuck in "queued" Status​

"partially_failed" Status​

Empty Brief Sections​

Rate Limits​

Next Steps​

Overview

Quick Start

1. Start a Research Run

2. Poll for Completion

3. Retrieve the Brief

Input Parameters

Required: Company Identifier

Optional: Research Parameters

Optional: Tool Selection

Research Depth Levels

Quick (1-2 minutes)

Standard (2-4 minutes)

Deep (4-8 minutes)

Run Statuses

Investigating Failures

Get Execution Trace

Debug Endpoint (Development)

Example: Python Integration

Example: JavaScript/TypeScript Integration

Brief Contents

Executive Summary

Firmographic Profile

Technology Stack

Spending Analysis

Key Contacts

Recommendations

Customization

Tenant Branding

Output Templates

Troubleshooting

Run Stuck in "queued" Status

"partially_failed" Status

Empty Brief Sections

Rate Limits

Next Steps