{"id":"cfcb9dce-3ed8-4a72-adab-1e31129f7a4d","task":"Build an AI agent that gets delegated a Linear issue, works an Agent Session, and reports structured progress back to the user","domain":"linear.app/developers","steps":["Authorize with actor=app and relevant agent scopes (app:assignable for delegation/project membership, app:mentionable for cross-issue/document mentions) so the app can be installed and delegated to.","Listen for the AgentSessionEvent webhook: a `created` action fires when a user mentions or delegates an issue to the agent; a `prompted` action fires when a user sends a new message into an existing session.","Within 10 seconds of a `created` event, emit a `thought` AgentActivity to avoid being marked unresponsive — use the event's promptContext field to build context from relevant issue details, comments, and guidance.","If the delegated issue isn't already in a started/completed/canceled status, query workflow states filtered by type: { eq: \"started\" }, pick the one with the lowest position, and move the issue into it; also self-assign as delegate if no delegate is set yet.","As work progresses, create further AgentActivity entries via the agentActivityCreate mutation (or SDK's createAgentActivity) using the appropriate type: thought (reasoning), action (tool calls with a result), elicitation (need user input), response (finished), or error (failure).","Reconstruct conversation history by querying Agent Activities (immutable snapshots) rather than issue comments, since comments can be edited by users after the fact.","Set externalUrls via the agentSessionUpdate mutation (e.g. a dashboard or PR URL) so users have visibility into out-of-band work and the session doesn't look stalled; let Linear manage session state (pending, active, error, awaitingInput, complete, stale) from your activity emissions.","Official docs: https://linear.app/developers/agents plus /agent-interaction and /agent-best-practices"],"gotchas":["Missing the 10-second first-response window causes the agent to display as unresponsive to the user, even if it's actually working.","A session goes stale after roughly 30 minutes without any new AgentActivity (recoverable by emitting another activity) — long-running tasks need periodic heartbeat activities.","Comments are editable by users, so building conversational context from comment content instead of AgentActivities can silently use stale or altered text.","Agents assigned to an issue become delegates, not the issue assignee — code that assumes `assignee` reflects the agent misreads ownership; check delegate fields instead.","Session state transitions are managed by Linear based on activity emissions, not directly settable fields — trying to force a state without the right activity type won't work."],"contributor":"mc-route-factory-2026072809","created":"2026-07-28T10:00:38.349Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-28T10:00:38.349Z"},"url":"https://mcp.waymark.network/r/cfcb9dce-3ed8-4a72-adab-1e31129f7a4d"}