Deep Research to Internal Documents

Audience: Developers

Deep Research to Internal Documents

Run deep research over internal documents using the Internal Profile. The profile enables the agent to use knowledge_retrieval (internal knowledge base) and connector_search (external connectors such as Google Calendar, GitHub, Drive) so that answers are grounded in your internal and connected data.

Important: Currently, both connector_search and knowledge_retrieval are strictly limited to one set of credentials per tool (one knowledge-retrieval service, one connector client). Support for multiple credentials or tenant-specific configuration is planned as a future enhancement.

Prerequisites

• The INTERNAL profile is available (created and stored in the database).

• The tools knowledge_retrieval and connector_search are registered and part of the Internal Profile.

• The environment variable AVAILABLE_TOOLS includes knowledge_retrieval and connector_search so the service can load them at runtime.

Those two tools are registered in the application and attached to the profile via its params.tools list. They must also be present in AVAILABLE_TOOLS (e.g. AVAILABLE_TOOLS=...,knowledge_retrieval,connector_search).

GL Open DeepResearch staging: The INTERNAL profile is already available. To run deep research over internal documents on staging, jump to Consume: Use the SDK with the Internal Profile and use profile=INTERNAL directly—no profile creation needed.

For other environments, or to create or change the Internal Profile, expand the section below.

Prepare the Internal Profile (for non-staging or custom setup)

The Internal Profile is a Tongyi profile that specifies only the internal-facing tools. Create or update it via the Profiles API (master API key required).

1. Ensure tools are available at runtime

Set the environment so the orchestrator can load the tools. In your .env or deployment config:

• AVAILABLE_TOOLS — Include knowledge_retrieval and connector_search in the comma-separated list, for example:

  AVAILABLE_TOOLS=web_search,web_search_map,fetch_web_page,knowledge_retrieval,connector_search

• knowledge_retrieval — Set:

  • KNOWLEDGE_RETRIEVAL_BASE_URL — Base URL of the internal knowledge retrieval service.

  • KNOWLEDGE_RETRIEVAL_KEY — API key for that service. (Currently one credentials set only; multi-credentials support is a future enhancement.)

• connector_search — Configure authentication for the connectors (e.g. Google, GitHub) as required by the connector client used by the tool. (Currently one credentials set only; multi-credentials support is a future enhancement.)

2. Create the Internal Profile via the Profiles API

Create a profile named INTERNAL (or another name you will use in requests) with provider tongyi and params.tools set to the two internal tools. Use the Profiles API (master API key required); see API Contract — Profiles for request body and endpoints. The important part for internal documents is "tools": ["knowledge_retrieval", "connector_search"] in params. Adjust model, max_tokens, max_depth, and timeout_seconds to match your environment.

Consume: Use the SDK with the Internal Profile

Once the Internal Profile is available (on staging it already is—use profile=INTERNAL directly), send research requests with the GL Open DeepResearch SDK (gl-odr-sdk) using profile=INTERNAL.

Single query

from gl_odr_sdk import DeepResearchClient

client = DeepResearchClient()

task = client.tasks.create(
    query="Summarize key decisions from our internal knowledge base and calendar.",
    profile="INTERNAL",
)
print(f"Task ID: {task.task_id}")

Multiple queries (taskgroup)

taskgroup = client.taskgroups.create(
    profile="INTERNAL",
    query=[
        "What does the internal wiki say about X?",
        "What meetings are relevant to project Y?",
    ],
)
print(f"Taskgroup ID: {taskgroup.taskgroup_id}")
print(f"Tasks: {taskgroup.tasks}")

Use the returned taskgroup_id and tasks to stream events (client.taskgroups.stream or client.tasks.stream) or poll for status and results (client.taskgroups.get, client.taskgroups.get_task). See Quick Start Guide and Run Multiple Queries with Async Taskgroup.

Summary

1. Set the AVAILABLE_TOOLS environment variable to include knowledge_retrieval and connector_search. Also configure any required tool-specific environment variables (e.g., KNOWLEDGE_RETRIEVAL_BASE_URL, KNOWLEDGE_RETRIEVAL_KEY).

2. Create the INTERNAL profile via the Profiles API, specifying provider: "tongyi" and params.tools: ["knowledge_retrieval", "connector_search"].

3. Use the SDK: client.tasks.create(...) or client.taskgroups.create(...) with profile=INTERNAL and your query(s).

For more on profiles and tools, see Research Profiles and Taskgroups API Contract.