Creating Workflow Templates

This guide covers the anatomy of workflow templates and best practices for creating effective, reusable research workflows.

Template Anatomy

A workflow template consists of:

Field	Required	Description
`name`	Yes	Template name for identification
`prompt`	Yes	Research prompt with Jinja2 placeholders
`description`	No	Human-readable description
`expected_input`	No	Schema defining required inputs
`content_filter`	No	Restrictions on searchable content
`research_plan`	No	Predefined steps for structured execution
`expected_output`	No	Report template describing how the final answer should look

Basic Template Structure

{
  "name": "Company Financial Analysis",
  "description": "Comprehensive financial analysis for any public company",
  "prompt": "Analyze {{ company_id }} from an investment perspective. Include financial metrics, competitive position, and growth outlook.",
  "expected_input": {
    "company_id": {
      "type": "rp_entity_id"
    }
  }
}

Input Types

`rp_entity_id`

Use for Bigdata entity identifiers (companies, ETFs, etc.):

{
  "expected_input": {
    "company_id": {"type": "rp_entity_id"},
    "competitor_id": {"type": "rp_entity_id"}
  }
}

Entity IDs can be found using the Knowledge Graph API.

`string`

Use for free-form text input:

{
  "expected_input": {
    "topic": {"type": "string"},
    "region": {"type": "string"}
  }
}

Example prompt using string inputs:

Research {{ topic }} trends in the {{ region }} market.
Focus on key players, regulatory changes, and investment opportunities.

Content Filters

Restrict which sources the research uses:

Filter by Document Type

{
  "content_filter": {
    "any_of": [
      {
        "type": "DOCUMENT_TYPE",
        "document_types": [
          {"type": "TRANSCRIPT", "subtype": "Earnings Call"},
          {"type": "FILING"}
        ]
      }
    ]
  }
}

Filter by Source

{
  "content_filter": {
    "any_of": [
      {
        "type": "SOURCE_TYPE",
        "sources_ids": ["ABC123", "DEF456"]
      }
    ]
  }
}

Exclude Specific Content

{
  "content_filter": {
    "none_of": [
      {
        "type": "DOCUMENT_TYPE",
        "document_types": [
          {"type": "NEWS"}
        ]
      }
    ]
  }
}

Available Document Types

Type	Subtypes
`TRANSCRIPT`	Earnings Call, General Conference Call, Investor Conference Call, etc.
`TRANSCRIPT-PRESENTATION`	Same subtypes as TRANSCRIPT
`FILING`	RNS-SEC-10-K, RNS-SEC-10-Q, RNS-SEC-8-K, etc.
`NEWS`	(no subtypes)

Research Plans

Add a research plan for structured, step-by-step execution:

{
  "research_plan": {
    "title": "Comprehensive Credit Analysis",
    "steps": [
      {"description": "Gather company background and business model"},
      {"description": "Analyze recent financial statements and leverage metrics"},
      {"description": "Review credit ratings and analyst commentary"},
      {"description": "Assess key credit risks and mitigants"},
      {"description": "Evaluate liquidity and debt maturity profile"},
      {"description": "Formulate investment recommendation"}
    ]
  }
}

When a research_plan is provided, the agent follows your predefined steps for structured, predictable output. Without a plan, the agent dynamically determines research steps based on your prompt.

Expected Output

The prompt controls what the agent researches. The expected_output field controls what the final report looks like: its section headings, ordering, table schemas, and tone. Setting it is the reliable way to get consistent, comparable reports across runs and across different companies.

{
  "expected_output": "# Company Analysis\n## Executive Summary\n## Financial Overview\n| Metric | Value | YoY Change |\n| --- | --- | --- |\n## Competitive Position\n## Risks\n## Outlook"
}

Keep the two fields as separate concerns. Research instructions belong in the prompt; report structure belongs in expected_output. Mixing them is the most common cause of reports that drift in format from one run to the next.

expected_output describes the output format only, so it cannot contain {{ placeholders }}. Placeholders belong in the prompt, where they are matched against expected_input. A template with a placeholder in expected_output is rejected on create and update.

Be explicit about anything you want standardized. To force a section to always render as a table, give it a fixed column schema. To drop a recurring intro sentence, say so directly (e.g. “Present results directly, without an introductory line”). Unspecified formatting is chosen by the model per run.

Complete Example

Here’s a complete template for M&A transaction analysis:

{
  "name": "M&A Transaction Analysis",
  "description": "Detailed analysis of merger or acquisition transactions",
  "prompt": "Analyze the {{ transaction_type }} involving {{ acquirer_id }} and {{ target_id }}. Include:\n\n1. Transaction overview and strategic rationale\n2. Financial terms and valuation analysis\n3. Synergy expectations and integration risks\n4. Regulatory considerations\n5. Market reaction and analyst views\n6. Impact on competitive landscape",
  "expected_input": {
    "acquirer_id": {"type": "rp_entity_id"},
    "target_id": {"type": "rp_entity_id"},
    "transaction_type": {"type": "string"}
  },
  "content_filter": {
    "any_of": [
      {
        "type": "DOCUMENT_TYPE",
        "document_types": [
          {"type": "NEWS"},
          {"type": "FILING"},
          {"type": "TRANSCRIPT", "subtype": "Special Situation, M&A and Other"}
        ]
      }
    ]
  },
  "research_plan": {
    "title": "M&A Analysis Framework",
    "steps": [
      {"description": "Research transaction details and timeline"},
      {"description": "Analyze deal terms and valuation metrics"},
      {"description": "Evaluate strategic fit and synergy potential"},
      {"description": "Review regulatory filings and antitrust considerations"},
      {"description": "Gather analyst reactions and market sentiment"},
      {"description": "Synthesize findings and outlook"}
    ]
  },
  "expected_output": "# M&A Transaction Analysis\n## Transaction Overview\n## Financial Terms & Valuation\n| Metric | Value |\n| --- | --- |\n## Synergies & Integration Risks\n## Regulatory Considerations\n## Market Reaction\n## Competitive Impact"
}

Creating Templates via API

import requests
from dotenv import load_dotenv
import os

load_dotenv()
my_api_key = os.getenv('BIGDATA_API_KEY')

template = {
    "name": "Quarterly Earnings Preview",
    "description": "Pre-earnings analysis for upcoming quarterly reports",
    "prompt": """Prepare an earnings preview for {{ company_id }} ahead of their upcoming quarterly report.

Include:
1. Consensus estimates (revenue, EPS)
2. Key metrics to watch
3. Recent business developments
4. Management guidance and commentary
5. Analyst sentiment and price targets
6. Potential catalysts or risks""",
    "expected_input": {
        "company_id": {"type": "rp_entity_id"}
    },
    "content_filter": {
        "any_of": [
            {
                "type": "DOCUMENT_TYPE",
                "document_types": [
                    {"type": "TRANSCRIPT", "subtype": "Earnings Call"},
                    {"type": "NEWS"}
                ]
            }
        ]
    }
}

response = requests.post(
    "https://agents.bigdata.com/v1/workflow/templates",
    headers={
        "X-API-KEY": my_api_key,
        "Content-Type": "application/json"
    },
    json=template
)

created = response.json()
print(f"Created template: {created['id']}")
print(f"Name: {created['name']}")

Best Practices

Clear, specific prompts: Include numbered sections or bullet points for structured output
Appropriate input types: Use rp_entity_id for entities to enable entity-aware search
Content filters: Restrict to relevant document types for focused research
Research plans: Add plans for complex, multi-step analyses
Expected output: Define expected_output when you need consistent report structure across runs; keep format out of the prompt
Descriptive names: Use clear template names for easy identification
Documentation: Add descriptions explaining the template’s purpose

How to guides

Research Service

Search Service

Proprietary Content

Knowledge Graph

Template Anatomy

Basic Template Structure

Input Types

`rp_entity_id`

`string`

Content Filters

Filter by Document Type

Filter by Source

Exclude Specific Content

Available Document Types

Research Plans

Expected Output

Complete Example

Creating Templates via API

Best Practices

Next Steps

Research Plans

Example Templates

​Template Anatomy

​Basic Template Structure

​Input Types

​rp_entity_id

​string

​Content Filters

​Filter by Document Type

​Filter by Source

​Exclude Specific Content

​Available Document Types

​Research Plans

​Expected Output

​Complete Example

​Creating Templates via API

​Best Practices

​Next Steps

Research Plans

Example Templates

Template Anatomy

Basic Template Structure

Input Types

`rp_entity_id`

`string`

Content Filters

Filter by Document Type

Filter by Source

Exclude Specific Content

Available Document Types

Research Plans

Expected Output

Complete Example

Creating Templates via API

Best Practices

Next Steps