Skip to navigation
API ReferenceAgentsGeneral

Invoke General Agent Asynchronously

Beta

Start a general-agent run and return immediately with a thread_id. Use this instead of /agents/general/invoke for any call that may take more than a few seconds (tool use, multi-step work), so the HTTP connection is never held open past client or proxy timeouts. Poll GET /threads/{thread_id}/status until status is completed or failed; pass include_messages=true to read the agent’s reply. Supply the thread_id of a general-agent thread you can access to continue it; 404/403 when it is unknown/not yours, 409 while a run is still in progress on it or while it is archived (restore it to continue it).

Authentication

X-API-KEYstring
API Key authentication via header

Headers

X-Athena-Session-CredentialstringOptional

Request

This endpoint expects an object.
configobjectRequired
Configurable fields for the agent.
messageslist of objectsRequired

The messages to send to the agent. Each message should be a string (for text inputs) or a list of multimodal content parts.

channelstringOptionalDefaults to api
The channel through which the request is being made.
thread_idstring or nullOptional
Optional thread ID for conversation persistence. If not provided, a new thread will be created.

Response

Successful Response
messagestring

Human-readable status message

statusstring

Status of the invocation (always ‘started’ for async)

thread_idstring

Thread ID of the run. Poll GET /threads/{thread_id}/status (client.threads.get_status) until status is ‘completed’ or ‘failed’; pass include_messages=true to read the agent’s reply.

Errors

403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error