Profiles

Audience: Developers

Research Profiles

Overview

Research profiles provide a convenient way to pre-configure provider settings and parameters for different research scenarios. Profiles are stored in the database and managed via the Profiles API (create, read, update, delete). The profile format is JSON in all API requests and responses. You must specify a profile name in each research request; the system loads that profile from the database and uses its provider and parameters for the run.

On first-time deployment, database migrations create the profiles table and seed three default profiles: TONGYI, GPTR-QUICK, and GPTR-DEEP. The default profile (e.g. GPTR-QUICK) is configured via environment variable and is used when a request does not specify a profile name (where applicable). You can add more profiles at any time via the Profiles API (master API key required).

---

User Guide

This section is for users who want to use existing profiles in their research requests.

What are Profiles?

A profile is a named configuration that includes:

• Provider: Which research provider to use (tongyi or gptr)

• Parameters: Provider-specific settings (LLM models, timeouts, research depth, etc.)

• Description: Human-readable description of the profile's purpose

Benefits

• Simplified Requests: Use a profile name instead of specifying all parameters

• Consistent Configuration: Ensure consistent settings across requests

• Easy Switching: Switch between different research configurations easily

List Available Profiles

Profiles are read from the database. List all available profiles with the Profiles API (master API key required):

curl http://localhost:8000/v1/profiles \
  -H 'X-API-Key: your-master-api-key'

Response:

{
  "profiles": [
    {
      "name": "TONGYI",
      "provider": "tongyi",
      "params": {
        "model": "Alibaba-NLP/Tongyi-DeepResearch-30B-A3B",
        "max_tokens": 10000,
        "temperature": 0.6,
        "max_depth": 7,
        "timeout_seconds": 900
      },
      "description": "Tongyi Deep Research Agent..."
    },
    {
      "name": "GPTR-QUICK",
      "provider": "gptr",
      "params": {
        "config_data": {...},
        "report_type": "research_report"
      },
      "description": "GPT-Researcher profile with SmartSearch..."
    }
  ],
  "default_profile": "GPTR-QUICK"
}

Using a Profile with Task or Taskgroup API

Use the task or taskgroup API for research requests. Include the profile name in each request.

Create a task group (form data)

curl -X POST 'https://stag-gl-deep-research.obrol.id/v1/taskgroup' \
  -H 'X-API-Key: your-account-api-key' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'query=What are the latest developments in quantum computing?' \
  --data-urlencode 'profile=GPTR-QUICK'

Create a single task (form data)

curl -X POST 'http://localhost:8000/v1/tasks' \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "query=What are the latest developments in quantum computing?" \
  -d "profile=GPTR-QUICK"

Examples

Example 1: Use an existing profile

Use a profile that is already in the database (e.g. one of the seeded defaults: TONGYI, GPTR-QUICK, GPTR-DEEP). No setup required beyond a valid API key.

curl -X POST 'https://stag-gl-deep-research.obrol.id/v1/taskgroup' \
  -H 'X-API-Key: your-account-api-key' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'query=What are the latest developments in quantum computing?' \
  --data-urlencode 'profile=GPTR-QUICK'

Save the returned taskgroup_id and tasks array; use them to stream (GET /v1/taskgroup/{id}/stream) or poll for status and result. See Quick Start Guide.

Example 2: Create a new profile and use it

Create a new profile via the Profiles API (master API key required), then run research with that profile using the task or taskgroup API.

Step 1 — Create the profile

curl -X POST 'https://stag-gl-deep-research.obrol.id/v1/profiles' \
  -H 'X-API-Key: your-master-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "GPTR-QUICK-CLAUDE",
    "provider": "gptr",
    "params": {
      "config_data": {
        "RETRIEVER": "custom",
        "SCRAPER": "smart_search",
        "EMBEDDING": "openai:text-embedding-3-small",
        "SMART_LLM": "anthropic:claude-3-5-sonnet-20241022",
        "STRATEGIC_LLM": "anthropic:claude-3-5-sonnet-20241022"
      },
      "report_type": "research_report"
    },
    "description": "Same as GPTR-QUICK but uses Claude (requires Anthropic API key)."
  }'

Step 2 — Run research with the new profile (taskgroup)

curl -X POST 'https://stag-gl-deep-research.obrol.id/v1/taskgroup' \
  -H 'X-API-Key: your-account-api-key' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'query=What are the latest developments in quantum computing?' \
  --data-urlencode 'profile=GPTR-QUICK-CLAUDE'

For more profile options and the full API contract, see Profiles API, Tasks API, Taskgroups API, and the Developer Guide below.

API Endpoints

List Profiles

Endpoint: GET /v1/profiles

Response: List of all available profiles with their configurations

Run research with a profile

Use task or taskgroup endpoints:

• Create task: POST /v1/tasks — single query, returns task_id

• Create taskgroup: POST /v1/taskgroup — one or more queries, shared profile/webhook, returns taskgroup_id and tasks

Request parameters (form or JSON as per API contract): query (required), profile (required). See Tasks API and Taskgroups API.

---

Developer Guide

This section is for developers who need to maintain, create, or modify profiles.

Where Profiles Are Stored

Profiles are stored in the database (PostgreSQL). They are not read from YAML or config files at runtime. The application loads profiles via the ProfileService from the database; the ConfigResolver and ProfileRegistry use this data for every research request.

Default Profiles on First Deploy

When you deploy GL Open DeepResearch for the first time, run the database migrations. A data migration seeds three default profiles into the database:

Profile	Provider	Description
TONGYI	tongyi	Tongyi Deep Research agent (LLM, tools, research params).
GPTR-QUICK	gptr	GPT-Researcher with Smart Search; quick research report.
GPTR-DEEP	gptr	GPT-Researcher with Smart Search; deep research (breadth/depth/concurrency).

The default profile name (e.g. GPTR-QUICK) is set via the DEFAULT_PROFILE environment variable. At least one profile must exist in the database for the application to start.

Profile Structure

Each profile is represented as JSON in the database and in all API requests and responses. A profile object contains:

• name: Unique identifier for the profile (string)

• provider: Provider type, "tongyi" or "gptr" (string)

• params: Object of provider-specific parameters (JSON object)

• description: Optional description (string)

Provider-Specific Parameters

When creating or updating profiles via the API, send a JSON body with the structure below. The seeded TONGYI, GPTR-QUICK, and GPTR-DEEP profiles follow these shapes.

Tongyi profile (JSON)

Example request body for provider tongyi:

{
  "name": "TONGYI",
  "provider": "tongyi",
  "params": {
    "model": "Alibaba-NLP/Tongyi-DeepResearch-30B-A3B",
    "max_tokens": 10000,
    "max_retries": 10,
    "temperature": 0.6,
    "top_p": 0.95,
    "presence_penalty": 1.1,
    "planning_port": 8000,
    "max_depth": 7,
    "timeout_seconds": 900,
    "tools": ["web_search", "web_search_map", "fetch_web_page", "web_page_snippets"]
  },
  "description": "Tongyi Deep Research Agent."
}

base_url and api_key are always loaded from environment variables (LLM_BASE_URL, LLM_API_KEY), not from the profile.

GPT-Researcher profile (JSON)

Example for a quick research profile (GPTR-QUICK style):

{
  "name": "GPTR-QUICK",
  "provider": "gptr",
  "params": {
    "config_data": {
      "RETRIEVER": "custom",
      "SCRAPER": "smart_search",
      "EMBEDDING": "openai:text-embedding-3-small",
      "SMART_LLM": "openai:gpt-4.1",
      "STRATEGIC_LLM": "openai:o4-mini"
    },
    "report_type": "research_report",
    "tools": ["web_search", "web_search_urls", "fetch_web_page"]
  },
  "description": "GPT-Researcher with Smart Search; quick research report."
}

For a deep research profile (GPTR-DEEP style), use "report_type": "deep" and add to config_data: DEEP_RESEARCH_BREADTH, DEEP_RESEARCH_DEPTH, DEEP_RESEARCH_CONCURRENCY.

Environment Variable Fallback

Profile parameters can reference environment variables. If a parameter is empty or missing, the system falls back to environment variables:

Tongyi Environment Variables:

• MODEL_NAME → model

• MAX_TOKENS → max_tokens

• MAX_RETRIES → max_retries

• TEMPERATURE → temperature

• TOP_P → top_p

• PRESENCE_PENALTY → presence_penalty

• PLANNING_PORT → planning_port

GPT-Researcher Environment Variables:

• OPENAI_API_KEY → Used for OpenAI API calls

Creating New Profiles

New profiles are created via the Profiles API (POST /v1/profiles) and stored in the database. This requires a master API key. For a full workflow example (create a profile, then run research with it), see Example 2: Create a new profile and use it in the Examples section above.

For the full API contract and request/response shapes, see the Profiles API documentation.

Profile Resolution Logic

When a research request is made:

1. Profile is required: The request must include a profile name.

2. Load from database: The profile is loaded from the database by name (via ProfileRegistry / ProfileService).

3. Use provider and params: The profile’s provider and params determine which research adapter runs and with which settings (Tongyi or GPT-Researcher).

Best Practices

1. Use Profiles for Common Scenarios: Create profiles in the database for frequently used configurations.

2. Descriptive Names: Use clear, descriptive profile names (e.g. TONGYI-DEEP, GPTR-QUICK).

3. Document Parameters: Include descriptions when creating/updating profiles so users know when to use each.

4. Environment Variables: Use environment variables for sensitive data (API keys, URLs); do not store secrets in profile params.

5. Validate Before Deploying: Test new or updated profiles before relying on them in production.

6. Default Profile: Ensure DEFAULT_PROFILE (env) matches a profile that exists in the database so the app can start and defaults work as expected.