Tasks & Executions

Executions capture the complete state of an agent processing messages in a chat room. Tasks let agents manage structured work within executions. Together they give you full observability into what agents do and why.

Agents vs Executions

An agent is a definition: its name, system prompt, model, and tools. Think of it like a class. An execution is a runtime instance of that definition, scoped to a specific chat room.

• One execution per agent per chat room
• The same agent can have multiple executions across different chat rooms, each independent
• Executions may share memories, but aside from that each execution is isolated and doesn’t affect other executions of the same agent

When a new message arrives for the agent:

1. The platform loads the existing execution from the database
2. The execution’s conversation history is provided to the LLM
3. The agent processes the message through one or more reasoning cycles
4. The updated execution state is saved back to the database

Context Isolation

Each execution operates in isolation, even when multiple executions of the same agent run concurrently.

Execution A’s tool results don’t leak to Execution B. Each execution maintains its own conversation history, tool calls, and state. Parallel executions don’t interfere with each other.

Why isolation matters:

• Security: Sensitive data in one execution stays there
• Reliability: One execution’s failure doesn’t corrupt another’s state
• Scalability: Thousands of executions can run without coordination overhead

Execution Lifecycle

Executions progress through defined states as the agent processes messages:

Reasoning Cycles

When an agent processes a message, it goes through one or more reasoning cycles. Each cycle is an iteration of the think-act-observe loop:

1. Think: The LLM analyzes the situation and decides on the next action
2. Act: The agent calls a tool or generates a response
3. Observe: The result is processed and added to context
4. Repeat or respond: Continue cycling or deliver the final response

A simple request might complete in one cycle. A complex task involving multiple tool calls may take many cycles. The platform enforces a maximum of 20 reasoning cycles per execution to prevent infinite loops.

What Executions Capture

Every execution maintains a complete record of:

• Messages: The full conversation from the agent’s perspective
• Tool calls: Every tool invocation with parameters and results
• Execution state: Runtime metadata, including the last processed message
• Errors: Timestamped error history for debugging

Tasks

A task is a trackable unit of work assigned to an agent. Tasks support hierarchical structures, status tracking, and error recording.

Task Entity

Task Types

Task Lifecycle

Tasks progress through defined states:

Hierarchical Tasks

Tasks can have sub-tasks, enabling complex workflows to be broken down into manageable pieces. A parent task tracks the overall objective while child tasks represent individual steps.

Parent Task: "Analyze Q4 market data"
  ├── Sub-task: "Gather sales figures from 3 sources"
  ├── Sub-task: "Cross-reference data points"
  └── Sub-task: "Write summary report"

Each sub-task has its own status and can fail independently without failing the parent.

How Tasks and Executions Connect

• An agent has one execution per chat room
• Each execution has a participation task as its parent
• The participation task contains work tasks created during the conversation
• The execution records all messages, tool calls, and state

Structured Outputs

When configured, agents respond in validated JSON instead of free-form text. This lets agents manage tasks, track progress, and maintain internal reasoning in a format the platform can parse and act on.

Required JSON Format

1
{
2
  "task_title": "Main objective description",
3
  "status": "processing",
4
  "tasks": [
5
    {
6
      "id": "1",
7
      "task": "Sub-task description",
8
      "status": "in_progress",
9
      "error": "",
10
      "summary": "Current state of this sub-task"
11
    }
12
  ],
13
  "thoughts": "Internal reasoning about current approach"
14
}

Top-Level Status Management

The top-level status field controls the agent’s execution flow:

Task Management Through the Tasks Array

Agents create and update sub-tasks through the tasks array in their structured response.

Creating new tasks: Use id: "1" (or any numeric string). The platform replaces this with a system-generated UUID.

1
{
2
  "tasks": [
3
    {
4
      "id": "1",
5
      "task": "Search for Q4 sales data",
6
      "status": "new",
7
      "error": "",
8
      "summary": ""
9
    }
10
  ]
11
}

Updating existing tasks: Use the UUID that was assigned by the system.

1
{
2
  "tasks": [
3
    {
4
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
5
      "task": "Search for Q4 sales data",
6
      "status": "completed",
7
      "error": "",
8
      "summary": "Found 3 reliable data sources with Q4 figures"
9
    }
10
  ]
11
}

Sub-task statuses:

Complete Example

A full structured output from an agent managing a research task:

1
{
2
  "task_title": "European EV Market Analysis",
3
  "status": "processing",
4
  "tasks": [
5
    {
6
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
7
      "task": "Gather Q4 sales data",
8
      "status": "completed",
9
      "error": "",
10
      "summary": "Found 3 sources: ACEA, Bloomberg NEF, IEA"
11
    },
12
    {
13
      "id": "1",
14
      "task": "Cross-reference data points across sources",
15
      "status": "new",
16
      "error": "",
17
      "summary": ""
18
    },
19
    {
20
      "id": "2",
21
      "task": "Write summary report with key findings",
22
      "status": "new",
23
      "error": "",
24
      "summary": ""
25
    }
26
  ],
27
  "thoughts": "Data gathering is complete. Three reliable sources found. Next step is to cross-reference the numbers before writing the report. Sales figures from ACEA and Bloomberg match, but IEA uses different methodology. Will note methodology differences in the report."
28
}

In this response:

• The first task (existing UUID) is updated to completed
• Two new tasks are created (IDs “1” and “2” will be replaced with UUIDs)
• The agent’s status is processing, so it will continue to the next reasoning cycle
• Thoughts capture the reasoning for debugging purposes

Schema Configuration

Structured outputs are enabled by setting the structured_output_schema field on an agent. This field accepts a JSON Schema that defines the expected response format.

1
{
2
  "json_schema": {
3
    "name": "taskowner_response",
4
    "schema": {
5
      "additionalProperties": false,
6
      "properties": {
7
        "status": {
8
          "description": "The current status of the task execution",
9
          "enum": ["processing", "waiting", "failed"],
10
          "type": "string"
11
        },
12
        "task_title": {
13
          "description": "The title of the current task",
14
          "type": "string"
15
        },
16
        "tasks": {
17
          "description": "List of sub-tasks and their status",
18
          "items": {
19
            "additionalProperties": false,
20
            "properties": {
21
              "id": { "type": "string" },
22
              "task": { "type": "string" },
23
              "status": {
24
                "enum": ["reviewing", "in_progress", "completed",
25
                         "failed", "engaging", "waiting", "new"],
26
                "type": "string"
27
              },
28
              "error": { "type": "string" },
29
              "summary": { "type": "string" }
30
            },
31
            "required": ["id", "task", "status", "error", "summary"],
32
            "type": "object"
33
          },
34
          "type": "array"
35
        },
36
        "thoughts": {
37
          "description": "Agent's internal thoughts (not shown to users)",
38
          "type": "string"
39
        }
40
      },
41
      "required": ["task_title", "status", "tasks", "thoughts"],
42
      "type": "object"
43
    },
44
    "strict": true
45
  }
46
}

Next Steps