`run_assistant`

Run an agent once, right now, with a message — how you test a colleague you just built, or re-run one to see what it does.

The run is headless: the agent acts as your organization’s system user, with its configured tools, integrations and skills — exactly as a scheduled run would. Platform-internal agents (the suggestion pipeline, the opportunity investigator) are refused; your own colleagues and the user-visible platform agents are fine.

This spends a real agent run. The dispatch is asynchronous — poll get_assistant_run with the returned thread_id until status is completed, failed or interrupted.

Parameters#

Name	Type	Required	Default	Description
`assistant_id`	string	yes		The agent id (from this server’s `list_assistants`, or `get_creation_guide` in chat)
`message`	string	yes		What the agent wakes up to — a real instruction, the same text a schedule would send it

Returns#

json

{
  "thread_id": "thread_abc123",
  "assistant_id": "assistant_xyz",
  "status": "queued",
  "note": "Dispatched asynchronously; this spends a real run. Poll get_assistant_run(thread_id) ..."
}

Errors#

`error_type`	When
`auth_error`	Missing / invalid API key
`permission_denied`	The credential’s user lacks `CAN_MANAGE_WORKFLOW`, or the caller is a headless agent
`not_found`	Unknown agent id, or one outside your organization
`invalid_input`	Empty `message`, or a platform-internal agent

The test loop#

Build or change the colleague (create_assistant / update_assistant on this workflows server, configure_assistant in chat).
run_assistant(assistant_id, message) → thread_id.
Poll get_assistant_run until terminal; read reply, tool_calls and suggestions.
Adjust the instructions and run again.