Developing the Agent Interaction

Once your agent is installed and authenticated, it can begin participating in workflows inside Linear. Agents become active participants through the Agent Session and Agent Activity system—primitives that make agent behavior visible, contextual, and collaborative for end users.

The following sections walk through how your agent will receive instructions though webhooks, how it should communicate back through Agent Activities, and how the Agent Session lifecycle helps track it all.

You can use the GraphQL schema explorer to look up the object types used in agent webhook payloads.

Agent session⁠

AgentSession tracks the lifecycle of an agent run. Session states let the user know if the agent is currently working, waiting for user input, in an error state, or has finished work. An AgentSession is created automatically when an agent is mentioned or delegated an issue.

Session states⁠

Agent sessions can have one of 5 states: pending, active, error, awaitingInput, complete. These will be visible to users.

You don’t need to manage agent session state manually. Linear tracks session lifecycle automatically based on the last emitted activity.

Session external URL⁠

You can set an externalUrl on an AgentSession so users can open the current session on your web dashboard.

Use the agentSessionUpdateExternalUrl mutation to set this value. Pass null to remove it.

Session webhooks⁠

An AgentSession webhook is sent to notify your agent when it's mentioned, delegated an issue through assignment, or when a user provides additional prompts.

To receive these events, enable the agent session events webhooks category in your OAuth application configuration.

You must return a response from your webhook receiver within 5 seconds.

AgentSessionEvent webhooks only send events to your specific agent.

There will be two types of actions in the AgentSessionEvent category, denoted by the action field of the payload:

For a detailed reference of all Agent Session webhook fields, see the AgentSessionEventWebhookPayload schema.

Proactively creating sessions⁠

If your agent was not delegated or mentioned but you would like to proactively create an agent session, you can do so via the SDK or API with the agentSessionCreateOnIssue or agentSessionCreateOnComment mutations.

Agent activity⁠

Agents communicate progress by emitting semantic agent activities to an AgentSession. These activities can represent thoughts, tool calls, prompts for clarification, final responses, or errors.

Sending agent activities⁠

Agents should communicate progress by emitting Agent Activities to Linear. These activities can represent thoughts, actions, prompts for clarification, final responses, or errors.

You can emit activities using either the TypeScript SDK or a direct GraphQL mutation:

TypeScript SDK

const { success, agentActivity } = await linearClient.createAgentActivity({
  agentSessionId: "...",
  content: {
    type: "...", 
    ... // other payload fields - see below
  },
});

GraphQL

# Operation
mutation AgentActivityCreate($input: AgentActivityCreateInput!) {
  agentActivityCreate(input: $input) {
    success
    agentActivity {
      ...
    }
  }
}
 
# Variables
{
	"input": {
		"agentSessionId": "...",
        # Shape of `content` varies by activity `type`
		"content": {
			"type": "...",
			... # other payload fields - see below
		} 
	}
}

To include mentions in Agent Activity content, use plain Linear URLs in Markdown. These will be converted into mentions in the UI. For example:

Renders as: "@user, I've created a new Linear issue for tracking the documentation work: @LIN-123 docs issue — please review.".

More on mentions in Adding mentions in Markdown.

Activity content payload⁠

Your agent may emit one of five allowed activity types. These are validated server-side, and invalid shapes will be rejected. Unless otherwise noted, all fields shown are required. Markdown is supported in body fields.

{
  "content": {
    "type": "thought",
    "body": "The user asked about the weather."
  }
}

{
  "content": {
    "type": "elicitation",
    "body": "Where are you located? I will find the current weather for you"
  }
}

{
  "content": {
    "type": "action",
    "action": "Searching",
    "parameter": "San Francisco Weather",
    // "result": undefined (optional)
  }
}

{
  "content": {
    "type": "action",
    "action": "Searched",
    "parameter": "San Francisco Weather",
    "result": "12°C, mostly clear" // Markdown OK
  }
}

{
  "content": {
    "type": "response",
    "body": "The weather in San Francisco is currently **foggy**, no surprise there."
  }
}

{
  "content": {
    "type": "error",
    "body": "Out of credits. [Pay up!](https://agent.com/pay)"
  }
}

Additionally, you may see references to a prompt type AgentActivity. That is a user-generated message, usually as a follow-up prompt or responding to an elicitation. These are the messages that emit a prompted webhook to you on creation.

An agent cannot generate a prompt type activity.

Signals⁠

Signals are optional metadata that modify how an Agent Activity should be interpreted or handled by the recipient. They provide additional context about the sender’s intent—guiding how the activity should be processed or responded to.

For details on available signals and sample usage, see Signals.

Ephemeral activities⁠

When creating an agent activity, you may optionally mark it as ephemeral. Ephemeral activities are displayed temporarily, and will be replaced when the next activity arrives from the agent. This could be helpful when displaying temporary states.

Only thought or action type activities can be marked ephemeral.

Recommendations⁠

For recommendations on improving agent interaction—like managing delegation and status updates—continue to best practices.