Skip to main content
Trinity
Guides/Self-Execute

Self-Execute (Background Tasks)

Allow an agent to run a background task on itself while keeping the chat responsive. The agent tells the user "I'm working on that in the background" and the result appears when ready.

How It Works

1

Agent calls chat_with_agent targeting itself with parallel=true.

2

Trinity creates a background execution tracked as a SELF_TASK activity.

3

The chat session stays responsive.

4

When complete, the result optionally injects into the chat.

Agent (in chat) -> "Let me research that in the background"
       |
       v
MCP chat_with_agent(self, inject_result=true)
       |
       v
Background execution starts -> Activity panel shows progress
       |
       v
Execution completes -> Result appears in chat (collapsed)

MCP Tool Usage

mcp__trinity__chat_with_agent({
  agent_name: "my-agent",      // Same as calling agent
  message: "Research the top 5 competitors",
  parallel: true,              // Required for background execution
  async: true,                 // Returns immediately
  inject_result: true,         // Insert result into chat when done
  chat_session_id: "session-abc-123"  // Current session ID
})

The call returns immediately with an execution_id. The result appears in chat when the task completes.

REST API

POST /api/agents/my-agent/task

{
  "message": "Research competitor pricing",
  "async_mode": true,
  "inject_result": true,
  "chat_session_id": "session-abc-123"
}

Activity Tracking

Self-tasks appear in the activity panel with:

•Activity type: self_task
•Triggered by: self_task
•Agent name: The agent running the background work

WebSocket Events

Task started:

{
  "type": "agent_activity",
  "activity_type": "self_task",
  "activity_state": "started",
  "action": "Background task: Research competitor...",
  "details": {
    "execution_id": "exec-123",
    "inject_result": true
  }
}

Task completed:

{
  "type": "agent_activity",
  "activity_type": "self_task",
  "activity_state": "completed",
  "details": {
    "cost_usd": 0.05,
    "execution_time_ms": 45000,
    "result_injected": true
  }
}

Chat Display

Self-task results appear in chat with distinct styling:

•Purple background
•"Background Task Result" header
•Collapsed by default (click to expand)
•Shows preview when collapsed

Use Cases

•Research tasks: "Research this topic while I continue chatting"
•File processing: "Process these files in the background"
•Code generation: "Generate that component, I'll check it when done"
•Batch operations: "Run those 10 queries, show me results when ready"

Security and Limitations

Security

•The X-Source-Agent header must match the MCP key's agent scope.
•Result injection validates session ownership before inserting.

Limitations

•No cancellation UI yet — running self-tasks cannot be stopped from chat.
•No real-time progress streaming — only start/complete events.
•Session must be owned by the same user for result injection.
SchedulingFan-Out