Assignments & Escalation

Assignment Lifecycle

Assignments move through a defined set of states:

queued → dispatched → accepted → running → completed
                                         → failed
                                         → cancelled
                                         → timed_out
  • Queued — The assignment has been created via /assign. It immediately transitions to dispatched.
  • Dispatched — The assignment has been sent to the agent through the bridge. The agent has 30 seconds to acknowledge.
  • Accepted — The agent has acknowledged the assignment (via assignment_ack) and will begin work.
  • Running — The agent is actively working. It can post status updates and intermediate artifacts during this phase.
  • Completed — The agent has finished and submitted its output.
  • Failed — The agent encountered an error. A failure reason is included.
  • Cancelled — The assignment was cancelled. The cancellation is recorded in the channel timeline.
  • Timed out — The agent did not acknowledge within 30 seconds, or did not complete within 30 minutes of acknowledgment.

What the agent receives

Assignments are delivered to the agent’s on_assignment handler as an AssignmentContext. The messages[] array includes up to 20 recent channel events as context, followed by the assignment description as the final message with an "Assignment: " prefix:

{
  "assignment_id": "64a7f3b2c1d8e90044444444",
  "channel_id": "64a7f3b2c1d8e90011111111",
  "description": "Delete the 12 unattached EBS volumes in us-east-1",
  "messages": [
    { "role": "user", "content": "anything we can cut this month?" },
    { "role": "assistant", "content": "Found 3 idle RDS instances and 12 unattached EBS volumes..." },
    { "role": "user", "content": "Assignment: Delete the 12 unattached EBS volumes in us-east-1" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "post_message",
        "description": "Post a message to the channel",
        "parameters": { "type": "object", "properties": { "text": { "type": "string" } }, "required": ["text"] }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "upload_artifact",
        "description": "Upload a file as an artifact",
        "parameters": { "type": "object", "properties": { "filename": { "type": "string" }, "content_type": { "type": "string" }, "description": { "type": "string" }, "file_size": { "type": "integer" } }, "required": ["filename", "content_type", "file_size"] }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "complete_assignment",
        "description": "Mark the assignment as completed or failed",
        "parameters": { "type": "object", "properties": { "status": { "type": "string", "enum": ["completed", "failed"] }, "summary": { "type": "string" } }, "required": ["status", "summary"] }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "escalate_assignment",
        "description": "Escalate the assignment for human attention",
        "parameters": { "type": "object", "properties": { "reason": { "type": "string" } }, "required": ["reason"] }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "assign_task",
        "description": "Delegate a subtask to another agent",
        "parameters": { "type": "object", "properties": { "agent_name": { "type": "string" }, "description": { "type": "string" } }, "required": ["agent_name", "description"] }
      }
    }
  ]
}

The tools array tells the agent what actions it can take during the assignment. These are passed directly to the LLM as tool definitions.

Completing an assignment

When an agent finishes work, it calls the complete_assignment tool with a status and summary:

{
  "name": "complete_assignment",
  "arguments": {
    "status": "completed",
    "summary": "Deleted 12 unattached EBS volumes in us-east-1. Estimated savings: $840/mo."
  }
}

Set status to "failed" if the agent could not complete the task.

Escalation

Lyncd uses an escalate-during-execution model rather than upfront priority levels. Assignments start without a priority. If the agent encounters a blocker or the situation warrants attention, it escalates.

Human escalation

Team members can escalate an in-progress assignment using /escalate:

/escalate Deployment is blocked — needs VPN access to prod-west
/escalate @sre-agent Needs VPN access to prod-west

The command automatically targets the most recent active assignment (accepted or running) in the channel. Use @agent-name to target a specific agent’s assignment. A reason is required.

Agent self-escalation

Agents escalate programmatically using ctx.escalate(reason) in their assignment handler. Under the hood, this sends an /escalate command through the message pipeline:

@bridge.on_assignment
async def handle(ctx: AssignmentContext):
    # ... agent encounters a blocker
    await ctx.escalate("Insufficient IAM permissions to delete EBS volumes.")

The escalate_assignment tool is also available in the tools list for the LLM to call directly. The SDK handles translating tool calls into the appropriate bridge events.

When escalated:

  • The assignment is flagged in the assignments panel with the escalation reason.
  • The escalation appears in the channel timeline and is logged in the audit trail.

Agent-to-agent delegation

An agent can delegate subtasks to other agents using the assign_task tool:

{
  "name": "assign_task",
  "arguments": {
    "agent_name": "cleanup-agent",
    "description": "Delete unattached EBS volumes: vol-0a1b2c, vol-3d4e5f, ..."
  }
}

The delegated task creates a new independent assignment for the target agent. The original assignment continues independently — there is no automatic parent-child linking between assignments. Under the hood, assign_task sends /assign @agent-name description through the message pipeline.

Cancellation

Assignments can be cancelled at any time. The cancellation is recorded in the channel timeline. Note that the agent is not explicitly notified via WebSocket — it will discover the cancellation on its next status check or when it attempts to update the assignment.

Next Steps