// troubleshooting

Getting help

Search the docs with agnt_support_docs_search, then file a support ticket with agnt_support_ticket_create. What to put in the subject, body and context, how to read the team's reply, and what never to send.

When a failure is not covered by these pages, or the docs say it is on our side and it keeps happening, ask the superagnt_ team. A person on the team reads every ticket and replies on it. Your agent can do the whole loop itself: search the docs, open a ticket, read the reply, and answer back.

These tools keep working when a plan has lapsed or a trial has ended, so a paused workspace can still ask for help.

Search the docs first

agnt_support_docs_search takes query (plain words) and an optional limit from 1 to 10 (default 5). It returns matches, each with slug, title, heading_path, content, similarity and url. url is the page's address on superagnt.com when the page is published there, and null otherwise.

Put the error code and the subject in the query, for example DATA_CREDITS_EXHAUSTED trial data credit or INTEGRATION_NOT_CONNECTED reconnect. If the search itself fails with PROVIDER_UNAVAILABLE, skip it and open the ticket.

Open a ticket

agnt_support_ticket_create takes:

Argument	Required	What to put in it
`subject`	yes	One line, up to 200 characters. Name the tool or path and the error: `connection_hubspot_create_contact returns INTERNAL_ERROR on every call`.
`category`	yes	One of `bug`, `question`, `billing`, `connection`, `feature_request`, `other`.
`body`	yes	Up to 20,000 characters. What you were trying to do, what you expected, what happened instead, and what you already tried.
`context`	no	A JSON object, up to 16,000 characters serialized, holding the facts that reproduce it.

It returns ticket_id, status (open) and next_step. Keep the ticket_id: it is how you read the answer later.

Pick the category by what needs fixing:

bug: superagnt_ behaves wrong, for example a repeated INTERNAL_ERROR or a result that contradicts these docs.
question: you need an answer, not a fix.
billing: credits, plans, charges or invoices.
connection: a vendor connection will not connect, or keeps failing while it shows as connected.
feature_request: something you need that does not exist yet.
other: anything else.

What to put in context

Key	What it holds
`error_code`	The code you got, for example `PROVIDER_ERROR`, or the offer's `reason`.
`http_status`	The HTTP status, when there was one.
`error_message`	The error message, as returned.
`tool_name`	The MCP tool you called, or the REST method and path.
`request_id`	Any request or trace id a response gave you.
`arguments`	The arguments you sent, with secrets and personal data replaced by `[redacted]`.
`occurred_at`	When it happened, as an ISO 8601 UTC timestamp. This is how the team finds the call in our logs, so be exact.

Add anything else that reproduces it: the data source or vendor, the connection's upstreamStatus and upstreamError, the MCP client you run in, how many times it failed and over what period. Keep full response bodies out: the error and the identifiers are enough.

agnt_support_ticket_createjson

{
  "subject": "connection_hubspot_create_contact returns INTERNAL_ERROR on every call",
  "category": "bug",
  "body": "Creating a contact through the HubSpot connection has failed on every call since about 14:05 UTC. Reading contacts on the same connection still works. I retried three times with backoff over ten minutes. The connection shows as connected in the superagnt app.",
  "context": {
    "error_code": "INTERNAL_ERROR",
    "http_status": 500,
    "error_message": "Internal server error",
    "tool_name": "connection_hubspot_create_contact",
    "arguments": { "email": "[redacted]", "firstname": "[redacted]", "lifecyclestage": "lead" },
    "occurred_at": "2026-10-06T14:07:31Z"
  }
}

never send secrets

Never put an API key, an MCP or OAuth token, a password, a connection credential or a card number in a subject, body or context. The team never needs one to help you, and will never ask for one.

File one ticket per problem. A workspace can open up to 10 tickets in a rolling hour, and past that agnt_support_ticket_create returns RATE_LIMITED. When you learn something new about a problem you already filed, reply on that ticket instead of opening another.

A dry run, when an agent is being test-run while it is built, never opens a real ticket.

Read the reply

A person answers, so a reply is not instant. Check back on a later turn, or when the person you work for asks. Do not poll in a tight loop.

The workspace owner also gets the team's reply by email (and so does the person whose account opened the ticket, when that is someone else), and people in the workspace see it in the help widget in the superagnt app.

agnt_support_ticket_get takes ticket_id and returns the ticket (ticket_id, subject, category, status, opened_via, last_message_at, created_at, closed_at), every message on it, and next_step. Each message has message_id, author, body, context and created_at. author is support for the superagnt_ team, agent for an AI agent (with deployed_agent_id when it was a deployed agent), and member for a person in the workspace.

agnt_support_tickets_list takes an optional status and limit (1 to 50, default 20) and lists this workspace's tickets, most recent activity first.

Status	What it means
`open`	Waiting on the superagnt_ team. Nobody has picked it up yet.
`pending`	Someone on the team is working on it.
`answered`	The team replied. The next move is yours.
`closed`	Done.

Reply on the ticket

agnt_support_ticket_reply takes ticket_id, body (up to 20,000 characters) and an optional context object, and returns ticket_id, message_id, status, reopened and next_step. A reply on an answered or closed ticket reopens it to open, and the team is told. A ticket accepts up to 30 messages from your side in a rolling hour.

Answer the team's questions here, and add anything new you learn, such as a fresh occurrence with its time.

Grouped tool names

Clients on the grouped tool surface see two support tools instead of five. The arguments are the same, plus an action:

Per-operation tool	Grouped tool and action
`agnt_support_docs_search`	`agnt_support_read`, action `search_docs`
`agnt_support_tickets_list`	`agnt_support_read`, action `list`
`agnt_support_ticket_get`	`agnt_support_read`, action `get`
`agnt_support_ticket_create`	`agnt_support_write`, action `create`
`agnt_support_ticket_reply`	`agnt_support_write`, action `reply`

For people

People can open and read tickets in the help widget in the superagnt app at https://app.superagnt.com, where the team's replies show up next to the ones your agents filed.