Skip to main content

HG Agents

HG Agents are AI-powered automation workflows that generate comprehensive research outputs using HG MCP Server tools. Agents run asynchronously and produce artifacts like HTML briefs, PDFs, or structured data.

What are HG Agents?​

Unlike interactive MCP tools that return immediate results, HG Agents:

  • Run asynchronously - Submit a request and poll for completion
  • Produce artifacts - Generate formatted outputs (HTML briefs, PDFs)
  • Use multiple tools - Orchestrate many MCP tools in a single workflow
  • Track execution - Provide traces for debugging and auditing

Available Agents​

AgentDescriptionOutput
Account Research BriefGenerate comprehensive account research briefs for sales enablementHTML brief
Buying Committee MapperMap stakeholders, assign buying roles, and recommend engagement strategiesHTML brief
Cold Email IcebreakerGenerate personalized 7-email cold outreach sequences with anti-AI detectionHTML sequence
ABM List BuilderBuild targeted account lists from marketing criteria (product, geography, revenue)HTML table
Campaign Account ScorerScore and rank accounts for ABM campaign prioritization using fit + intent signalsHTML report
Campaign Contact FinderFind target personas at accounts with spreadsheet-style contact tablesHTML table
Campaign Email DrafterDraft personalized outreach emails grounded in HG Insights dataHTML email

How Agents Work​

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ Your App │ │ Agent Service │ │ HG MCP Server │
│ │────▶│ (FastAPI) │────▶│ Tools │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ 1. Start run │ 2. Execute agent │
│ │ (calls tools) │
│ │ │
│ 3. Poll status │ │
│◀──────────────────────│ │
│ │ │
│ 4. Get artifacts │ │
│◀──────────────────────│ │
  1. Start a run - Submit input (company domain or ID) and parameters
  2. Agent executes - The agent calls multiple HG MCP Server tools to gather data
  3. Poll for status - Check run status until completion
  4. Retrieve artifacts - Download the generated brief or report

Agent Builder​

In the web app, the Agent Builder lets you edit an agent and run it.

  • Run tab. Fill in the agent's inputs in a form; invalid or missing inputs are flagged per field. Choose what to run: the saved draft (default) or a published version.
  • Save & Run. With unsaved edits the run button becomes Save & Run. It saves, validates, then runs; if a step fails, the message names it.
  • Form | YAML. Edit the definition as a form or as YAML. Format YAML tidies the text and Validate checks the text currently in the editor.
  • Leaving with unsaved edits. Switching agents asks whether to discard the edits or stay.
  • Templates. An agent created from a template shows "Based on template vN". When a newer template version exists, Update from template merges it into your agent field by field: changes only you made are kept, changes only the template made are taken, and fields changed on both sides are shown for you to choose. Reset to latest template discards your YAML and starts from the latest template.

Quick Example​

# 1. Start an account 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"}
}'

# Response: {"run_id": "abc-123", "status": "queued"}

# 2. Poll for completion
curl "https://phoenix.hginsights.com/api/agents/v1/runs/abc-123" \
-H "Authorization: Bearer YOUR_API_KEY"

# Response: {"run_id": "abc-123", "status": "succeeded", "progress": 1.0}

# 3. Get the generated brief
curl "https://phoenix.hginsights.com/api/agents/v1/runs/abc-123/artifacts" \
-H "Authorization: Bearer YOUR_API_KEY"

# Response: {"artifacts": [{"artifact_type": "html", "url": "/v1/runs/abc-123/artifacts/brief.html"}]}

Authentication​

HG Agents use the same API keys as HG MCP Server tools. Include your API key in the Authorization header:

Authorization: Bearer phx_your_api_key_here

To generate an API key:

  1. Log into HG Insights at https://phoenix.hginsights.com
  2. Navigate to Settings → API Keys
  3. Click Generate New API Key
warning

Keep your API keys secure. Never commit them to version control or share them publicly.

Next Steps​