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.

External session⁠

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.

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.

Agent 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.

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
		} 
	}
}

Initiating a session⁠

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.

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.

Agent Activity Signals⁠

Agent Activity Signals are optional modifiers that give your agent additional context on how to interpret or handle an activity.

A signal is metadata set by either an agent or a human user that tells the recipient how to respond—effectively communicating the sender’s intent beyond just reading the content.

Recommendations⁠

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