Structured Outputs

Audience: Developers

Structured outputs

Research results and streaming events have a consistent shape across the task and taskgroup APIs.

Task result shape

A completed task returns a payload like:

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "taskgroup_id": "660e8400-e29b-41d4-a716-446655440000",
  "status": "SUCCESS",
  "data": {
    "query": "What are the latest developments in quantum computing?",
    "result": "Based on my research, quantum computing has seen significant advances in 2024. Key developments include:\n\n1. **Quantum Error Correction**: Major breakthroughs in error correction codes have improved quantum computer stability.\n\n2. **Increased Qubit Counts**: Companies like IBM and Google have demonstrated systems with over 1000 qubits.\n\n3. **Practical Applications**: Real-world applications in drug discovery and financial modeling are showing promising results.\n\nSources:\n- Nature Quantum Information (2024)\n- IBM Research Blog\n- Google Quantum AI Publications",
    "profile": "ESSENTIAL",
    "created_at": "2024-12-02T10:00:00Z",
    "completed_at": "2024-12-02T10:00:45Z",
    "duration": 45.23
  },
  "error": ""
}

Field descriptions

• task_id: Unique identifier for the task (UUID format)

• taskgroup_id: ID of the taskgroup if the task belongs to one (null for standalone tasks)

• status: Task status - "SUCCESS", "FAILURE", "PENDING", "STARTED", "RECEIVED", "REVOKED", "RETRY"

• data.query: The original research query string

• data.result: The research findings and analysis as a string (may include markdown formatting, sources, citations)

• data.profile: Profile name used for research configuration (e.g., "ESSENTIAL", "COMPREHENSIVE", "INTERNAL")

• data.created_at: ISO 8601 timestamp when research was initiated

• data.completed_at: ISO 8601 timestamp when research was completed (null if not completed)

• data.duration: Duration in seconds (floating point number, null if not completed)

• error: Error message string if task failed (empty string if successful)

Using task results

You can use these fields to:

• Display results: Use data.result to show research findings to users

• Track progress: Use status to determine if research is complete

• Measure performance: Use data.duration to track research time

• Link related tasks: Use taskgroup_id to group related research tasks

• Handle errors: Check error field for error messages when status is "FAILURE"

With the SDK

With gl-odr-sdk, the same shape is exposed on the response objects:

result = client.tasks.get(task_id)
# result.status, result.error
if result.data:
    # result.data.query, result.data.result, result.data.profile
    # result.data.created_at, result.data.completed_at, result.data.duration
    print(result.data.result)

Streaming event types

SSE streams emit events such as:

• THINKING_START / THINKING / THINKING_END — Reasoning steps.

• ACTIVITY — Tool execution (e.g. search, fetch).

• RESPONSE — Final research result.

Each event is a JSON object with id, type, value, and level. Use type to drive UI (e.g. show "thinking" vs "activity" vs "done").

Event structure

All streaming events follow this structure:

{
  "id": "unique-event-id-uuid",
  "type": "EVENT_TYPE",
  "value": "event-content-or-object",
  "level": "info"
}

Event type examples

THINKING_START

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "THINKING_START",
  "value": "",
  "level": "info"
}

When to use: Show a "thinking" indicator in your UI when this event arrives.

THINKING

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "type": "THINKING",
  "value": "I need to research quantum computing developments. Let me break this down into sub-questions:\n1. Recent quantum hardware advances\n2. Software and algorithm improvements\n3. Real-world applications",
  "level": "info"
}

When to use: Display the thinking content (value as string) to show users what the research agent is reasoning about. You can append multiple THINKING events to show progressive reasoning.

THINKING_END

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "type": "THINKING_END",
  "value": "",
  "level": "info"
}

When to use: Hide the "thinking" indicator when this event arrives.

ACTIVITY

{
  "id": "550e8400-e29b-41d4-a716-446655440004",
  "type": "ACTIVITY",
  "value": {
    "message": "Executing web_search tool with parameters: query=quantum computing developments 2024"
  },
  "level": "info"
}

When to use: Show tool execution progress. The value is an object with a message field describing the activity. You can display this as "Searching..." or "Fetching page..." to show users what the research agent is doing.

Another ACTIVITY example:

{
  "id": "550e8400-e29b-41d4-a716-446655440005",
  "type": "ACTIVITY",
  "value": {
    "message": "Tool web_search completed successfully. Result: Found 10 relevant articles about quantum computing advances."
  },
  "level": "info"
}

RESPONSE

{
  "id": "550e8400-e29b-41d4-a716-446655440006",
  "type": "RESPONSE",
  "value": "Based on my research, quantum computing has seen significant advances in 2024. Key developments include:\n\n1. **Quantum Error Correction**: Major breakthroughs in error correction codes have improved quantum computer stability.\n\n2. **Increased Qubit Counts**: Companies like IBM and Google have demonstrated systems with over 1000 qubits.\n\n3. **Practical Applications**: Real-world applications in drug discovery and financial modeling are showing promising results.\n\nSources:\n- Nature Quantum Information (2024)\n- IBM Research Blog\n- Google Quantum AI Publications",
  "level": "info"
}

When to use: This is the final research result. Display value (as string) as the complete research findings. This matches the data.result field in task results.

Complete stream example

Here's what a complete stream looks like:

data:{"id":"550e8400-e29b-41d4-a716-446655440001","type":"THINKING_START","value":"","level":"info"}

data:{"id":"550e8400-e29b-41d4-a716-446655440002","type":"THINKING","value":"I need to research quantum computing developments. Let me break this down into sub-questions.","level":"info"}

data:{"id":"550e8400-e29b-41d4-a716-446655440003","type":"THINKING_END","value":"","level":"info"}

data:{"id":"550e8400-e29b-41d4-a716-446655440004","type":"ACTIVITY","value":{"message":"Executing web_search tool with parameters: query=quantum computing developments 2024"},"level":"info"}

data:{"id":"550e8400-e29b-41d4-a716-446655440005","type":"ACTIVITY","value":{"message":"Tool web_search completed successfully. Result: Found 10 relevant articles."},"level":"info"}

data:{"id":"550e8400-e29b-41d4-a716-446655440006","type":"RESPONSE","value":"Based on my research, quantum computing has seen significant advances...","level":"info"}

Using streaming events

You can use these events to:

• Show progress: Display THINKING_START/THINKING/THINKING_END to show reasoning progress

• Show activity: Display ACTIVITY events to show tool execution (searches, fetches)

• Show final result: Display RESPONSE event as the final research result

• Build UI state: Use type to drive different UI components (thinking spinner, activity log, result display)

• Store events: Save events to your database for later retrieval (events are also stored in Redis for 24 hours)

With the SDK

When streaming with gl-odr-sdk, each event has event_type, value, and other attributes:

for event in client.tasks.stream(task_id):
    # event.event_type, event.value (string or dict with "message")
    print(f"{event.event_type}: {event.value}")

Event value formats

• THINKING events: value is a plain string containing the thinking content

• ACTIVITY events: value is an object with a message field describing the activity

• RESPONSE events: value is a plain string containing the final research result

See Quick Start Guide for SDK usage and Tasks API Contract / Taskgroups API Contract for full schemas.