Tool calls

​

In discussions

​

Report a tool call

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

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

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

• toolCallId: yours, unique within the discussion, 1–256 characters of [A-Za-z0-9_-]
• text: required on every write, max 2000 characters. This is what the user reads.
• error: required on ERROR, max 4000 characters
• SUCCESS and ERROR are final. A later write returns result: NOOP.

​

Asking for approval

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;

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

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

• APPROVED: means your tool call was approved and you can run the tool.
• DENIED: means the user rejected your tool call. Your tool will have already been updated to a status of FAILED and will include the user’s reviewerNote if provided. This is a human-provided message as to why the tool call was rejected.
• If your agent stops waiting, report ERROR so the call doesn’t stay open.

​

Asking a question

const result = await plain.mutation.requestDiscussionQuestion({
  input: {
    discussionId: "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    questions: [
      {
        question: "Which invoice should I refund?",
        isMultiSelect: false,
        options: [
          { label: "INV-1042", description: "Charged on 2 September" },
          { label: "INV-1043", description: "Charged on 3 September" },
        ],
      },
    ],
  },
});

if (result.error) throw new Error(result.error.message);
const questionRequestId = result.question?.questionRequestId;

mutation requestDiscussionQuestion($input: RequestDiscussionQuestionInput!) {
  requestDiscussionQuestion(input: $input) {
    question {
      questionRequestId
      status
      questions {
        id
        question
        options {
          id
          label
        }
      }
    }
    error {
      message
      type
      code
    }
  }
}

{
  "input": {
    "discussionId": "thd_01HZ8A1B2C3D4E5F6G7H8J9K0M",
    "questions": [
      {
        "question": "Which invoice should I refund?",
        "isMultiSelect": false,
        "options": [
          { "label": "INV-1042", "description": "Charged on 2 September" },
          { "label": "INV-1043", "description": "Charged on 3 September" }
        ]
      }
    ]
  }
}

• questions: 1–4 per call. A card holds at most 8 across every ask.
• question: 1–500 characters. Set isMultiSelect to true to let the user pick more than one option.
• options: 2–4 per question. label is 1–80 characters and unique within the question, and description is 1–240 characters. Put the option you recommend first, and don’t add your own Other option.
• Asking while a card is open adds the new questions to that card, skipping any with the same text as one already on it. The response returns the whole card.
• Only the agent the discussion is bound to can ask, and not on a resolved discussion.

• ANSWERED: selections holds the option ids the user picked and any otherText they typed. Plain sets the discussion to IN_PROGRESS, so carry on with the answer and set IDLE when the turn ends.
• DISMISSED: the user closed the card without answering, and selections is empty. Plain sets the discussion to IDLE unless a tool call is still PENDING. Wait for the user’s next message.

​

On threads

const result = await plain.mutation.createThreadEvent({
  input: {
    threadId: thread.id,
    title: "Searched knowledge",
    components: [
      {
        componentText: {
          text: "Query: `refund policy`. 3 results, top match: **Refunds and cancellations**.",
        },
      },
    ],
    isCollapsed: true,
  },
});

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