Build an internal agent

Run your own agent inside of Plain, alongside Sidekick.

You can add custom internal agents in Plain alongside Sidekick. This page covers that surface: the events your agent receives, the mutations it calls back, and the tools it has available.

This is a different surface from a support agent, which answers a customer’s thread. Here your agent answers your own team, in a discussion, and nothing it writes reaches the customer.

How a turn works

A user asks a question, Plain sends you a webhook, and every visible state after that is one your agent reports:

1. A user opens a Sidekick discussion, picks your agent, and types a question.
2. Plain sends you discussion.message_created.
3. Your agent reports IN_PROGRESS, does its work, posts an answer, and reports IDLE.
4. For an action a person should decide first, your agent reports the call, asks for approval, and waits for discussion.tool_call_approval_resolved.

What you need in Plain

Your agent needs a machine user Plain recognizes as a custom agent, a webhook target on the right version, and the two SDKs.

1. Turn a machine user into a custom agent

   Your agent needs a machine user with the Custom agent toggle on. The toggle marks the machine user as an agent your workspace built, so a user can pick it when they start a Sidekick discussion.

   Give its API key these four permissions at minimum:

   • threadDiscussion:read: read the discussion and ask for approvals
   • threadDiscussion:edit: report agent status and resolve the discussion
   • threadDiscussionMessage:create: post answers and tool calls
   • threadDiscussionMessage:edit: resolve a tool call you started

   Add thread:read and customer:read if your agent reads the thread a discussion hangs off.

2. Subscribe to relevant webhooks

   Subscribe a webhook target to the discussion.* events your agent needs, and set its version to 2026-09-06.

   Event	Needed	What it is for
   discussion.message_created	Required	Drives every turn: a message arrived in a discussion your agent owns.
   discussion.tool_call_approval_resolved	Required for the approval gate	A user approved or denied a tool call your agent parked. Skip if your agent isn’t using approvals.
   discussion.tool_call_approval_requested	Optional	Mirrors the approval request your agent made itself.
   discussion.discussion_created	Optional	Announces a new discussion. The first discussion.message_created is enough to start a turn.

3. Install the SDKs

   Use @team-plain/graphql 3.0.0 or newer and @team-plain/webhooks 1.9.0.

   npm install @team-plain/graphql@3 @team-plain/webhooks@1.9.0
   

Decide whether to answer

Your own replies return to you as webhooks. Answer only when all four conditions hold:

Condition	Why
discussion.type is AGENT_SESSION	Other discussion types are between people, not agents.
discussion.agent.id is your machine user	Otherwise the discussion belongs to Sidekick or to another agent.
message.type is OUTBOUND	A person’s turn is OUTBOUND and your own replies return as INBOUND.
discussion.status is not RESOLVED	The discussion is over.

Call myMachineUser once at startup to learn your own id, and deduplicate on message.id so a retried delivery does not produce a second answer.

import { PlainClient } from "@team-plain/graphql";
import { verifyPlainWebhook } from "@team-plain/webhooks";

const plain = new PlainClient({ apiKey: process.env.PLAIN_API_KEY! });
const me = await plain.query.myMachineUser();

function shouldAnswer(payload: DiscussionMessageCreatedPublicEventPayload) {
  return (
    payload.discussion.type === "AGENT_SESSION" &&
    payload.discussion.agent?.id === me.id &&
    payload.message.type === "OUTBOUND" &&
    payload.discussion.status !== "RESOLVED"
  );
}

Answer the HTTP request with 200 before you start working to avoid webhook retries.

Post an answer

sendDiscussionMessage posts your agent’s reply into the discussion. It takes Markdown, and the message appears under your machine user’s public name.

Posting your answer is what marks the discussion unread for the user.

SDK

import { PlainClient } from "@team-plain/graphql";

const plain = new PlainClient({ apiKey: process.env.PLAIN_API_KEY! });

const result = await plain.mutation.sendDiscussionMessage({
  input: {
    discussionId: "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    markdownContent:
      "The invoice failed because the card was **declined** on 3 September.",
  },
});

if (result.error) throw new Error(result.error.message);

GraphQL

Mutation

mutation sendDiscussionMessage($input: SendDiscussionMessageInput!) {
  sendDiscussionMessage(input: $input) {
    discussionMessage {
      id
    }
    error {
      message
      type
      code
    }
  }
}

Variables

{
  "input": {
    "discussionId": "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    "markdownContent": "The invoice failed because the card was **declined** on 3 September."
  }
}

Read error on every response before you treat the call as done.

Report what your agent is doing

updateDiscussionAgentStatus reports your agent’s progress. Report IN_PROGRESS when the turn starts and IDLE when it ends, so the discussion stops showing work that has finished.

SDK

const result = await plain.mutation.updateDiscussionAgentStatus({
  input: {
    discussionId: "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    agentStatus: "IN_PROGRESS",
  },
});

if (result.error) throw new Error(result.error.message);

GraphQL

Mutation

mutation updateDiscussionAgentStatus($input: UpdateDiscussionAgentStatusInput!) {
  updateDiscussionAgentStatus(input: $input) {
    discussion {
      id
      agentStatus
    }
    error {
      message
      type
      code
    }
  }
}

Variables

{
  "input": {
    "discussionId": "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    "agentStatus": "IN_PROGRESS"
  }
}

Settle on IDLE when the turn fails too. Post the failure as a message first, so the user reads what went wrong, then report IDLE.

The mutation rejects TOOL_CALL_APPROVAL_PENDING and UNKNOWN. Plain sets the pending state itself when you ask for an approval, and it refuses IDLE and IN_PROGRESS while an approval is open.

Report tool calls

upsertDiscussionToolCall puts a line on the discussion for each call your agent makes, keyed by an id you choose. Report it as PENDING before the call and again with the same id afterwards, with SUCCESS or ERROR.

SDK

const result = await plain.mutation.upsertDiscussionToolCall({
  input: {
    discussionId: "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    toolCallId: "refund-1",
    status: "PENDING",
    text: "Refund the duplicate charge on invoice in_1234567890123",
  },
});

if (result.error) throw new Error(result.error.message);

// same toolCallId once the call returns: status SUCCESS or ERROR,
// and result comes back as UPDATED

GraphQL

Mutation

mutation upsertDiscussionToolCall($input: UpsertDiscussionToolCallInput!) {
  upsertDiscussionToolCall(input: $input) {
    toolCall {
      toolCallId
      status
      durationMs
    }
    result
    error {
      message
      type
      code
    }
  }
}

Variables

{
  "input": {
    "discussionId": "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    "toolCallId": "refund-1",
    "status": "PENDING",
    "text": "Refund the duplicate charge on invoice in_1234567890123"
  }
}

The call enforces four rules:

• toolCallId is yours, unique within the discussion, 1 to 256 characters of letters, digits, hyphens and underscores.
• text is required on every write, up to 2000 characters, and it is the line a user reads on the timeline.
• error is required when status is ERROR, up to 4000 characters.
• SUCCESS and ERROR are final. A later write to a settled call returns result: NOOP and changes nothing.

Gate an action on a user

Some actions should not run without human approval. Report the call, ask for an approval, and wait: Plain shows the user a card with the call’s text as the heading and your justification underneath, with Approve and Deny controls.

SDK

const result = await plain.mutation.requestDiscussionToolCallApproval({
  input: {
    discussionId: "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    toolCallId: "refund-1",
    justification:
      "The invoice was double charged, so I want to refund the duplicate.",
  },
});

if (result.error) throw new Error(result.error.message);
const approvalId = result.approval?.approvalId;

GraphQL

Mutation

mutation requestDiscussionToolCallApproval($input: RequestDiscussionToolCallApprovalInput!) {
  requestDiscussionToolCallApproval(input: $input) {
    approval {
      approvalId
      toolCallId
      status
    }
    error {
      message
      type
      code
    }
  }
}

Variables

{
  "input": {
    "discussionId": "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    "toolCallId": "refund-1",
    "justification": "The invoice was double charged, so I want to refund the duplicate."
  }
}

The call named by toolCallId must already be reported and still PENDING. Asking twice for the same call returns the same approval unchanged. Requesting one also moves the discussion to TOOL_CALL_APPROVAL_PENDING.

Plain then sends you discussion.tool_call_approval_requested, and discussion.tool_call_approval_resolved once a user decides:

• On APPROVED, run the call, then report the outcome with upsertDiscussionToolCall.
• On DENIED, do not run it, and do not report an error either. Plain has already failed the call with reviewerNote as its error.
• If you stop waiting, report the call as ERROR with a message saying so.

Resolve the discussion

agentStatus says what your agent is doing inside a turn. Whether the discussion is over is its own status, and changeThreadDiscussionStatus moves it:

SDK

const result = await plain.mutation.changeThreadDiscussionStatus({
  input: {
    threadDiscussionId: "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    status: "RESOLVED",
  },
});

if (result.error) throw new Error(result.error.message);

GraphQL

Mutation

mutation changeThreadDiscussionStatus($input: ChangeThreadDiscussionStatusInput!) {
  changeThreadDiscussionStatus(input: $input) {
    error {
      message
      type
      code
    }
  }
}

Variables

{
  "input": {
    "threadDiscussionId": "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    "status": "RESOLVED"
  }
}

Resolving is reversible: pass OPEN to reopen. Resolve only when the user needs nothing further, because a resolved discussion drops out of their view.

Reference implementation

team-plain/example-internal-agents is a working agent on this API. Read it for a complete example of the surface above.

Caveats

• Keep one model session per discussion, not per message. Store the discussion id against your model’s session handle and resume it, or every turn starts from nothing and the discussion has no memory.
• Nothing your agent posts in a discussion reaches the customer. A discussion is internal to your team, whatever thread it hangs off.