Skip to content

Running Tasks

Tasks are the primary way to interact with your AI team. You describe what you want done in natural language, and the system orchestrates the right agents and tools to complete it.

Execution Flow

sequenceDiagram
    participant U as User
    participant S as Shell
    participant C as Cloud
    participant A as Agent(s)
    participant T as MCP Tools

    U->>S: "Generate the weekly sales report"
    S->>C: task message (WebSocket)
    C->>A: Route to supervisor agent
    A->>C: tool_call (sheets:read_range)
    C->>S: tool_call message
    S->>T: JSON-RPC tools/call
    T-->>S: Tool result
    S->>C: tool_result message
    C->>A: Continue with result
    A->>C: Final response
    C->>S: task_response (is_final: true)
    S-->>U: Display result

Submitting a Task

Via the Shell UI

  1. Click the New Task button or press Ctrl+N
  2. Type your task description in natural language
  3. Press Send or Enter

Via the WebSocket tunnel

Tasks can be sent programmatically through the tunnel:

{
  "type": "task",
  "id": "task-uuid",
  "content": "Generate the weekly sales report for Q1",
  "manifest_id": "manifest-uuid",
  "timestamp": "2026-02-15T10:00:00Z"
}

Via the REST API

Create an execution directly:

curl -X POST https://api.gremia.io/api/v1/executions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shell_id": "shell-uuid",
    "manifest_id": "manifest-uuid",
    "task_description": "Generate the weekly sales report"
  }'

Execution Lifecycle

Each task creates an execution that progresses through these states:

stateDiagram-v2
    [*] --> Created: Task received
    Created --> Running: Agent assigned
    Running --> Running: Tool calls in progress
    Running --> Completed: Final output ready
    Running --> Failed: Error occurred
    Completed --> [*]
    Failed --> [*]
Status Description
created Execution registered, waiting for agent assignment
running Agent is processing; may involve multiple tool calls
completed Task finished successfully with final output
failed An error prevented completion

Execution Events

While a task is running, the Cloud streams events through the tunnel:

task_response

Intermediate and final responses from agents:

{
  "type": "task_response",
  "id": "task-uuid",
  "execution_id": "exec-uuid",
  "content": "{\"agent_id\":\"report-gen\",\"output\":\"Report ready...\"}",
  "is_final": false,
  "agent_id": "report-gen",
  "event_type": "step",
  "timestamp": "2026-02-15T10:00:05Z"
}

tool_call

When an agent needs to use a tool:

{
  "type": "tool_call",
  "id": "call-uuid",
  "execution_id": "exec-uuid",
  "server_id": "google-sheets",
  "tool_name": "read_range",
  "arguments": {
    "spreadsheet_id": "abc123",
    "range": "Sales!A1:D100"
  },
  "requires_approval": false,
  "correlation_id": "corr-uuid",
  "timestamp": "2026-02-15T10:00:02Z"
}

Monitoring Executions

Shell dashboard

The Shell UI shows:

  • Active tasks with real-time progress
  • Agent activity showing which agent is currently working
  • Tool call log with server, tool name, and duration
  • Final output when the task completes

REST API

List recent executions:

curl https://api.gremia.io/api/v1/executions \
  -H "Authorization: Bearer $TOKEN"

Get a specific execution:

curl https://api.gremia.io/api/v1/executions/{execution_id} \
  -H "Authorization: Bearer $TOKEN"

Stream events via SSE:

curl https://api.gremia.io/api/v1/executions/{execution_id}/events \
  -H "Authorization: Bearer $TOKEN"

Multi-Agent Coordination

For complex tasks, the supervisor agent delegates sub-tasks to specialized workers:

graph TD
    S[Supervisor Agent] -->|"Fetch data"| W1[Data Agent]
    S -->|"Analyze trends"| W2[Analysis Agent]
    S -->|"Generate report"| W3[Report Agent]
    W1 -->|tool_call| T1[Google Sheets MCP]
    W2 -->|tool_call| T2[Python MCP]
    W3 -->|tool_call| T3[Gmail MCP]
    W1 -->|result| S
    W2 -->|result| S
    W3 -->|result| S

The coordination follows the workflow graph defined in your manifest. Each node runs an agent, and edges define the handoff conditions.

Error Handling

When an execution fails:

  1. The Cloud sends a task_response with event_type: "error" and is_final: true
  2. The Shell displays the error message in the task panel
  3. The execution status is set to failed

Common failure causes:

Error Cause Resolution
Tool not found MCP server missing the requested tool Check manifest mcp_requirements
Server disconnected MCP server process crashed Restart the server from the Servers panel
Timeout Tool call took too long Increase timeout or simplify the request
Credit exhausted No remaining credits Upgrade your plan or wait for period reset
Approval rejected User rejected a tool call Re-submit the task and approve the tool call

Best Practices

  1. Be specific — "Generate a PDF report of Q1 sales by region" is better than "Make a report"
  2. Check server status — Ensure all required MCP servers are running before submitting
  3. Review approvals promptly — Pending approvals block execution progress
  4. Monitor credit usage — Complex tasks with many tool calls consume more credits
  5. Use the right model tier — Simple tasks do not need the powerful tier