Build an internal agent

Build an agent that answers your team in Ask Sidekick, next to Sidekick.

Build an agent that answers users in a discussion, next to Sidekick. Nothing it writes reaches the customer. For customer threads, see support agents.

Bring your own agent is currently in beta and free to use.

How a turn works

1. A user opens Ask Sidekick, picks your agent, and sends a prompt.
2. Plain sends discussion.message_created.
3. Your agent reports IN_PROGRESS, works, posts an answer, reports IDLE.
4. For an action a user must decide, the agent asks for approval and waits on discussion.tool_call_approval_resolved.

What you need

1. Create a custom agent

   Create a machine user with Type set to Custom agent (on an existing one, Change type). That is what makes it appear in Ask Sidekick.

   On Add API key, expand the non-recommended groups and grant threadDiscussion and threadDiscussionMessage:

   • threadDiscussion:read and threadDiscussion:edit: read, report status, ask for approvals, resolve or reopen. Status reporting needs both.
   • threadDiscussionMessage:create and threadDiscussionMessage:edit: post answers. upsertDiscussionToolCall also needs threadDiscussion:read.

   Add thread:read and customer:read if the agent reads the thread the discussion is on.

2. Subscribe to webhooks

   Go to Settings → Webhooks, click Add webhook target, pin version 2026-09-06, and subscribe to discussion.*. Copy the signing secret from Settings → Request signing.

   Event	Needed	Why
   discussion.message_created	Required	Every turn. Fires for every discussion in the workspace, so filter below.
   discussion.tool_call_approval_resolved	If you use approvals	A user approved or denied a call you parked.
   discussion.tool_call_approval_requested	Optional	Echo of the request you made.
   discussion.discussion_created	Optional	The first discussion.message_created is enough to start.

3. Install the SDKs

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

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

Decide whether to answer

Your own replies come back as webhooks. Answer only when all of these hold:

Condition	Why
discussion.type is AGENT_SESSION	Other discussion types are between users.
discussion.agent.id is your machine user	Otherwise it is Sidekick or another agent.
message.type is OUTBOUND	A user’s turn is OUTBOUND; your replies are INBOUND.
discussion.status is not RESOLVED	The discussion is over.

Call myMachineUser once at startup. Deduplicate on message.id.

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 Markdown as the machine user’s public name. That call is what marks the discussion unread.

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

Check error on the response.

Report what your agent is doing

updateDiscussionAgentStatus: IN_PROGRESS when the turn starts, IDLE when it ends (including after a failure: post the error as a message first).

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

You cannot set TOOL_CALL_APPROVAL_PENDING or UNKNOWN. Asking for an approval sets pending. You cannot set IDLE or IN_PROGRESS while an approval is open.

Report tool calls

upsertDiscussionToolCall is keyed by an id you choose. Report PENDING, then the same id as 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"
  }
}

• toolCallId: yours, unique in the discussion, 1–256 characters [A-Za-z0-9_-]
• text: required every write, max 2000 characters
• error: required on ERROR, max 4000 characters
• SUCCESS and ERROR are final; a later write returns result: NOOP

Gate an action on a user

Report the call, then ask for approval. Plain shows a card with text as the heading, justification underneath, and Approve / Deny.

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 toolCallId must already be PENDING. Asking again returns the same approval. The discussion moves to TOOL_CALL_APPROVAL_PENDING.

Then discussion.tool_call_approval_requested, and discussion.tool_call_approval_resolved when a user decides:

• APPROVED: run the call, then upsertDiscussionToolCall with the outcome.
• DENIED: do not run it and do not report ERROR. Plain already failed the call with reviewerNote.
• If you stop waiting: report ERROR.

Most decisions happen on the card. resolveDiscussionApproval is for your own review tooling. An agent’s API key is refused: it cannot approve itself.

SDK

// A human actor only: an agent's API key is refused here.
const result = await plain.mutation.resolveDiscussionApproval({
  input: {
    approvalId: "ap_01HZ8E6F7G8H9J0K1M2N3P4Q5R",
    decision: "APPROVED",
    reviewerNote: "Confirmed with finance, go ahead.",
  },
});

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

GraphQL

Mutation

mutation resolveDiscussionApproval($input: ResolveDiscussionApprovalInput!) {
  resolveDiscussionApproval(input: $input) {
    error {
      message
      type
      code
    }
  }
}

Variables

{
  "input": {
    "approvalId": "ap_01HZ8E6F7G8H9J0K1M2N3P4Q5R",
    "decision": "APPROVED",
    "reviewerNote": "Confirmed with finance, go ahead."
  }
}

Resolve the discussion

agentStatus is the turn. changeThreadDiscussionStatus opens or resolves the discussion.

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

Pass OPEN to reopen. Resolve when the user needs nothing further.

Example and caveats

Two working agents on this API, one per repository: example-aisdk-assistant-agent on the Vercel AI SDK, and example-eve-assistant-agent on eve, Vercel’s agent framework.

• Keep one model session per discussion, not per message.
• Nothing posted in a discussion reaches the customer.