Skip to main content

Manager API

The Manager API lets you run conversations with managers - orchestrators that plan a task, delegate work to their configured sub-agents, and report back to the user. You get the same conversation lifecycle as the Agent API, plus structured visibility into every sub-agent invocation.

All Manager API requests require the resourceId query parameter set to your manager ID and an Authorization header with your API key.

Base URL​

REST API:   https://api.autessa.com/clients/managers
WebSocket:  wss://api.autessa.com/ws/clients/managers/execute

Managers vs. Agents​

A manager does not answer the user directly from a single prompt. Instead it:

  1. Reasons about the request and breaks it into tasks
  2. Invokes one or more of its configured sub-agents, each running its own full agent conversation
  3. Relays sub-agent results, asks the user for clarification when needed (waitingForUserInput), and iterates until the task is complete

Compared to the Agent API, the request shapes are nearly identical (with managerId instead of agentId), while responses add manager-specific fields: waitingForUserInput, agentInvocationStatus, and subAgentStreamedOutput. Conversation logs use manager log types (INVOKE_AGENT_REQUEST, INVOKE_AGENT_RESPONSE, USER_REQUEST, ...) instead of agent log types.

Authentication​

HTTP REST APIs​

Pass your API key in the Authorization header (no "Bearer" prefix):

Authorization: your_api_key_here

WebSocket APIs​

Pass your API key as a query parameter:

authorization=your_api_key_here
curl https://api.autessa.com/clients/managers/execute-create?resourceId=V1StGXR8Z5 \
  -H "Authorization: your_api_key" \
  -H "Content-Type: application/json"

REST API Endpoints​

Create Conversation POST/execute-create​

Creates a new conversation for multi-turn manager interactions. A conversation maintains the manager's context - including all sub-agent activity - across multiple execute requests.

Note: Once created, a conversation is tied to a specific manager version. Even if you publish a new version, existing conversations will continue using the original version.

Query Parameters​

  • Name
    resourceId
    Type
    string
    Description

    The ID of the manager (e.g. V1StGXR8Z5).

Request Body​

  • Name
    managerId
    Type
    string
    Description

    The ID of the manager to create a conversation for.

  • Name
    version
    Type
    CustomVersion
    Description

    Optional version override. If not specified, uses the PUBLISHED version. See Custom Version.

Response​

  • Name
    conversationId
    Type
    string
    Description

    The unique ID for the created conversation. Use this in subsequent execute requests.

  • Name
    errors
    Type
    array<string>
    Description

    Array of error messages if any occurred.

  curl --request POST \
    --url 'https://api.autessa.com/clients/managers/execute-create?resourceId=V1StGXR8Z5' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: your_api_key' \
    --data '{
      "managerId": "V1StGXR8Z5"
    }'
JSON
{
  "conversationId": "conv_a1b2c3d4e5",
  "errors": []
}

Execute Manager POST/execute​

Executes a manager synchronously with multimodal input. The manager plans, invokes its sub-agents as needed, and returns the complete response once the orchestration finishes - which can take significantly longer than a single agent execution.

Note: Synchronous execution only supports TEXT output. For real-time streaming of manager reasoning and sub-agent activity, use the WebSocket endpoint.

Query Parameters​

  • Name
    resourceId
    Type
    string
    Description

    The ID of the manager (e.g. V1StGXR8Z5).

Request Body​

  • Name
    managerId
    Type
    string
    Description

    The ID of the manager to execute.

  • Name
    conversationId
    Type
    string
    Description

    The conversation ID from /execute-create. Required for multi-turn conversations.

  • Name
    input
    Type
    array<MultimodalInput>
    Description

    Array of multimodal inputs (text, audio, images, files). Same shapes as the Agent API - see Multimodal Input.

  • Name
    environmentVariables
    Type
    object
    Description

    Key-value pairs for environment variables that won't be stored on the server. Forwarded to sub-agent tool executions.

  • Name
    promptTemplateVariables
    Type
    object
    Description

    Key-value pairs to inject into the manager's prompt template. Variables are referenced in the manager instructions using @@{variableName}@@ syntax.

  • Name
    executionOutputMode
    Type
    string
    Description

    "TEXT" or "AUDIO" - desired output format. REST execution supports "TEXT" only.

Response​

  • Name
    output
    Type
    array<MultimodalOutput>
    Description

    Array of output responses from the manager.

  • Name
    waitingForUserInput
    Type
    boolean
    Description

    true if the manager paused to ask you a clarifying question instead of completing the task. Send your answer as the next /execute request in the same conversation.

  • Name
    errors
    Type
    array<string>
    Description

    Array of error messages if any occurred.

  curl --request POST \
    --url 'https://api.autessa.com/clients/managers/execute?resourceId=V1StGXR8Z5' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: your_api_key' \
    --data '{
      "managerId": "V1StGXR8Z5",
      "conversationId": "conv_a1b2c3d4e5",
      "input": [
        {
          "inputType": "TEXT",
          "content": "Research our top competitor and draft an outreach email."
        }
      ],
      "promptTemplateVariables": {
        "companyName": "Acme Corp"
      }
    }'
JSON
{
  "output": [
    {
      "outputType": "TEXT",
      "content": "I researched the competitor and drafted the outreach email. Here it is: ..."
    }
  ],
  "waitingForUserInput": false,
  "errors": []
}

Close Conversation POST/execute-close​

Closes an existing conversation. This triggers logging and any configured auto-evaluation for the conversation. It's safe to call this even for expired conversations.

Query Parameters​

  • Name
    resourceId
    Type
    string
    Description

    The ID of the manager (e.g. V1StGXR8Z5).

Request Body​

  • Name
    managerId
    Type
    string
    Description

    The ID of the manager.

  • Name
    conversationId
    Type
    string
    Description

    The conversation ID to close.

Response​

  • Name
    errors
    Type
    array<string>
    Description

    Array of error messages if any occurred.

  curl --request POST \
    --url 'https://api.autessa.com/clients/managers/execute-close?resourceId=V1StGXR8Z5' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: your_api_key' \
    --data '{
      "managerId": "V1StGXR8Z5",
      "conversationId": "conv_a1b2c3d4e5"
    }'
JSON
{
  "errors": []
}

Get Conversation POST/conversation​

Retrieves the complete conversation history including manager reasoning, every sub-agent invocation, and evaluation context.

Query Parameters​

  • Name
    resourceId
    Type
    string
    Description

    The ID of the manager (e.g. V1StGXR8Z5).

Request Body​

  • Name
    managerId
    Type
    string
    Description

    The ID of the manager.

  • Name
    conversationId
    Type
    string
    Description

    The conversation ID to retrieve.

  • Name
    expandAgents
    Type
    boolean
    Description

    When true, each INVOKE_AGENT_RESPONSE log inlines the full sub-agent conversation (invokeAgentResponse.agentContext), so you can see the sub-agent's own tool calls and messages. Defaults to false.

Response​

  • Name
    conversation
    Type
    ManagerConversationDto
    Description

    The complete conversation data. See Manager Conversation Structure.

  • Name
    errors
    Type
    array<string>
    Description

    Array of error messages if any occurred.

cURL
curl --request POST \
  --url 'https://api.autessa.com/clients/managers/conversation?resourceId=V1StGXR8Z5' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: your_api_key' \
  --data '{
    "managerId": "V1StGXR8Z5",
    "conversationId": "conv_a1b2c3d4e5",
    "expandAgents": false
  }'
JSON
{
  "conversation": {
    "resourceId": "V1StGXR8Z5",
    "version": "1",
    "conversationId": "conv_a1b2c3d4e5",
    "apiKeyId": "key_xyz",
    "closeDate": null,
    "currentIteration": 3,
    "logs": [
      {
        "logType": "USER_INPUT",
        "combinedMultimodalInput": [
          {
            "inputType": "TEXT",
            "content": "Research our top competitor and draft an outreach email."
          }
        ]
      },
      {
        "logType": "INVOKE_AGENT_REQUEST",
        "invokeAgentRequest": {
          "invocationId": "inv_9f8e7d",
          "toolCallId": "call_abc123",
          "agentId": "aB3dE5fG7h",
          "agentName": "ResearchAgent",
          "taskDescription": "Find the top competitor of Acme Corp",
          "variables": {
            "company": "Acme Corp"
          }
        }
      },
      {
        "logType": "INVOKE_AGENT_RESPONSE",
        "invokeAgentResponse": {
          "invocationId": "inv_9f8e7d",
          "toolCallId": "call_abc123",
          "agentId": "aB3dE5fG7h",
          "agentName": "ResearchAgent",
          "responseType": "COMPLETE",
          "summary": "Identified Globex Inc as the top competitor.",
          "conversationId": "conv_sub_1a2b3c",
          "success": true
        }
      },
      {
        "logType": "MESSAGE_TO_USER",
        "multimodalOutput": {
          "outputType": "TEXT",
          "content": "Your top competitor is Globex Inc. Here is the outreach email draft: ..."
        }
      }
    ]
  },
  "errors": []
}

Manager Conversation Structure​

The /conversation endpoint returns a ManagerConversationDto:

  • Name
    resourceId
    Type
    string
    Description

    The manager ID.

  • Name
    version
    Type
    string
    Description

    Manager version used for this conversation.

  • Name
    conversationId
    Type
    string
    Description

    Unique conversation ID.

  • Name
    apiKeyId
    Type
    string
    Description

    API key ID that created this conversation, or "my-sandbox" for conversations created in the builder.

  • Name
    closeDate
    Type
    datetime
    Description

    When the conversation was closed, or null if still active.

  • Name
    currentIteration
    Type
    integer
    Description

    Number of orchestration iterations the manager has used.

  • Name
    logs
    Type
    array<ManagerLog>
    Description

    Manager log entries in chronological order. See log types below.

  • Name
    evaluationContext
    Type
    object
    Description

    Human and automated evaluation results for this conversation, if any.

Log Types​

Each log entry has a logType field that determines which other fields are present:

  • Name
    USER_INPUT
    Description

    User input to the manager. Contains combinedMultimodalInput array.

  • Name
    MANAGER_REASONING
    Description

    The manager's planning/thinking output. Contains multimodalOutput.

  • Name
    MESSAGE_TO_USER
    Description

    The manager's final message to the user. Contains multimodalOutput.

  • Name
    INVOKE_AGENT_REQUEST
    Description

    The manager delegating a task to a sub-agent. Contains invokeAgentRequest.

  • Name
    INVOKE_AGENT_RESPONSE
    Description

    The sub-agent's result. Contains invokeAgentResponse.

  • Name
    USER_REQUEST
    Description

    The manager asking the user for clarification. Contains userRequest.

  • Name
    USER_RESPONSE
    Description

    The user's answer to a USER_REQUEST. Contains userResponse (string).

Sub-Agent Invocation Objects​

invokeAgentRequest (on INVOKE_AGENT_REQUEST logs):

  • Name
    invocationId
    Type
    string
    Description

    System-generated UUID for tracking this invocation.

  • Name
    toolCallId
    Type
    string
    Description

    The manager LLM's tool call ID.

  • Name
    agentId
    Type
    string
    Description

    Which sub-agent is being invoked.

  • Name
    agentName
    Type
    string
    Description

    The sub-agent's name.

  • Name
    taskDescription
    Type
    string
    Description

    The task given to the sub-agent.

  • Name
    context
    Type
    string
    Description

    Additional context passed to the sub-agent (optional).

  • Name
    variables
    Type
    object
    Description

    All tool arguments the manager supplied.

  • Name
    agentPromptTemplateVariables
    Type
    object
    Description

    Prompt template variables forwarded to the sub-agent.

  • Name
    executionOutputMode
    Type
    string
    Description

    Output mode passed to the sub-agent (TEXT or AUDIO).

  • Name
    multimodalInputs
    Type
    array<MultimodalInput>
    Description

    Multimodal inputs (e.g. images) forwarded to the sub-agent.

invokeAgentResponse (on INVOKE_AGENT_RESPONSE logs):

  • Name
    invocationId
    Type
    string
    Description

    Matches the invocationId from the corresponding request.

  • Name
    toolCallId
    Type
    string
    Description

    Matching tool call ID.

  • Name
    agentId
    Type
    string
    Description

    Which sub-agent responded.

  • Name
    agentName
    Type
    string
    Description

    The sub-agent's name.

  • Name
    responseType
    Type
    string
    Description

    "COMPLETE" (task finished) or "HELP" (the sub-agent needs more information).

  • Name
    summary
    Type
    string
    Description

    For COMPLETE: what was accomplished.

  • Name
    helpRequest
    Type
    string
    Description

    For HELP: what the sub-agent needs.

  • Name
    conversationId
    Type
    string
    Description

    The sub-agent's own conversation ID (usable for resuming).

  • Name
    success
    Type
    boolean
    Description

    Whether the sub-agent execution succeeded.

  • Name
    errorMessage
    Type
    string
    Description

    Error message if the sub-agent failed.

  • Name
    agentContext
    Type
    object
    Description

    Full sub-agent conversation. Only populated when expandAgents=true on /conversation.

userRequest (on USER_REQUEST logs):

  • Name
    question
    Type
    string
    Description

    What the manager is asking the user.

  • Name
    reason
    Type
    string
    Description

    Why this information is needed.

  • Name
    contextualInfo
    Type
    string
    Description

    Background context for the user.

{
  "logType": "INVOKE_AGENT_REQUEST",
  "invokeAgentRequest": {
    "invocationId": "inv_9f8e7d",
    "toolCallId": "call_abc123",
    "agentId": "aB3dE5fG7h",
    "agentName": "ResearchAgent",
    "taskDescription": "Find the top competitor of Acme Corp",
    "variables": {
      "company": "Acme Corp"
    },
    "executionOutputMode": "TEXT"
  }
}

Get Conversation Status POST/conversation-status​

Checks the current status of a conversation (IN_PROGRESS, CLOSED, or NOT_FOUND).

Query Parameters​

  • Name
    resourceId
    Type
    string
    Description

    The ID of the manager (e.g. V1StGXR8Z5).

Request Body​

  • Name
    managerId
    Type
    string
    Description

    The ID of the manager.

  • Name
    conversationId
    Type
    string
    Description

    The conversation ID to check.

Response​

  • Name
    conversationId
    Type
    string
    Description

    The conversation ID that was checked.

  • Name
    status
    Type
    string
    Description

    One of: IN_PROGRESS, CLOSED, NOT_FOUND

  • Name
    errors
    Type
    array<string>
    Description

    Array of error messages if any occurred.

cURL
curl --request POST \
  --url 'https://api.autessa.com/clients/managers/conversation-status?resourceId=V1StGXR8Z5' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: your_api_key' \
  --data '{
    "managerId": "V1StGXR8Z5",
    "conversationId": "conv_a1b2c3d4e5"
  }'
JSON
{
  "conversationId": "conv_a1b2c3d4e5",
  "status": "IN_PROGRESS",
  "errors": []
}

Revive Conversation POST/revive-conversation​

Revives a closed conversation, allowing you to continue the interaction where it left off - including the manager's sub-agent context.

Query Parameters​

  • Name
    resourceId
    Type
    string
    Description

    The ID of the manager (e.g. V1StGXR8Z5).

Request Body​

  • Name
    managerId
    Type
    string
    Description

    The ID of the manager.

  • Name
    conversationId
    Type
    string
    Description

    The conversation ID to revive.

Response​

  • Name
    conversationId
    Type
    string
    Description

    The revived conversation ID.

  • Name
    status
    Type
    string
    Description

    One of: REVIVED, NOT_FOUND, ALREADY_ACTIVE, INVALID_STATE, ERROR

  • Name
    errors
    Type
    array<string>
    Description

    Array of error messages if any occurred.

cURL
curl --request POST \
  --url 'https://api.autessa.com/clients/managers/revive-conversation?resourceId=V1StGXR8Z5' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: your_api_key' \
  --data '{
    "managerId": "V1StGXR8Z5",
    "conversationId": "conv_a1b2c3d4e5"
  }'
JSON
{
  "conversationId": "conv_a1b2c3d4e5",
  "status": "REVIVED",
  "errors": []
}

Generate Audio Upload Link POST/generate-audio-upload-link​

Generates a pre-signed S3 upload URL for audio files. Use this when you want to upload audio files separately rather than sending them as base64 in the request.

Note: Currently supports WAV format only.

Query Parameters​

  • Name
    resourceId
    Type
    string
    Description

    The ID of the manager (e.g. V1StGXR8Z5).

Request Body​

Currently empty (WAV format is hardcoded).

Response​

  • Name
    uploadUrl
    Type
    string
    Description

    Pre-signed URL for uploading the audio file via PUT request.

  • Name
    s3Uri
    Type
    string
    Description

    S3 URI to use in AudioInput when referencing this file.

  • Name
    expiresInSeconds
    Type
    integer
    Description

    Time in seconds until the upload URL expires.

  • Name
    errors
    Type
    array<string>
    Description

    Array of error messages if any occurred.

cURL
curl --request POST \
  --url 'https://api.autessa.com/clients/managers/generate-audio-upload-link?resourceId=V1StGXR8Z5' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: your_api_key' \
  --data '{}'
JSON
{
  "uploadUrl": "https://s3.amazonaws.com/autessa-audio/...",
  "s3Uri": "s3://autessa-audio/user-123/audio-xyz.wav",
  "expiresInSeconds": 3600,
  "errors": []
}
Upload the file
# Step 1: Get upload link
# Step 2: Upload audio file
curl --request PUT \
  --url 'https://s3.amazonaws.com/autessa-audio/...' \
  --header 'Content-Type: audio/wav' \
  --data-binary '@audio.wav'

# Step 3: Use s3Uri in AudioInput
# {
#   "inputType": "AUDIO",
#   "s3Uri": "s3://autessa-audio/user-123/audio-xyz.wav"
# }

Generate Image Upload Link POST/generate-image-upload-link​

Generates a pre-signed S3 upload URL for image files. Upload the image via PUT, then reference the returned s3Uri in an Image Input.

Query Parameters​

  • Name
    resourceId
    Type
    string
    Description

    The ID of the manager (e.g. V1StGXR8Z5).

Request Body​

  • Name
    fileExtension
    Type
    string
    Description

    Image file extension: png, jpg, or jpeg. Defaults to png if not provided.

Response​

  • Name
    uploadUrl
    Type
    string
    Description

    Pre-signed URL for uploading the image file via PUT request.

  • Name
    s3Uri
    Type
    string
    Description

    S3 URI to use in ImageInput when referencing this file.

  • Name
    mimeType
    Type
    string
    Description

    MIME type of the image (e.g. image/png). Use it as the Content-Type header when uploading, and in the ImageInput.

  • Name
    expiresInSeconds
    Type
    integer
    Description

    Time in seconds until the upload URL expires.

  • Name
    errors
    Type
    array<string>
    Description

    Array of error messages if any occurred.

cURL
curl --request POST \
  --url 'https://api.autessa.com/clients/managers/generate-image-upload-link?resourceId=V1StGXR8Z5' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: your_api_key' \
  --data '{
    "fileExtension": "png"
  }'
JSON
{
  "uploadUrl": "https://s3.amazonaws.com/autessa-images/...",
  "s3Uri": "s3://autessa-images/user-123/image-xyz.png",
  "mimeType": "image/png",
  "expiresInSeconds": 3600,
  "errors": []
}

Generate File Upload Link POST/generate-file-upload-link​

Generates a pre-signed S3 upload URL for document files (PDFs, text documents, etc.). Upload the file via PUT, then reference the returned s3Uri in a File Input.

Query Parameters​

  • Name
    resourceId
    Type
    string
    Description

    The ID of the manager (e.g. V1StGXR8Z5).

Request Body​

  • Name
    fileExtension
    Type
    string
    Description

    File extension of the document to upload (e.g. pdf, docx, txt).

Response​

  • Name
    uploadUrl
    Type
    string
    Description

    Pre-signed URL for uploading the file via PUT request.

  • Name
    s3Uri
    Type
    string
    Description

    S3 URI to use in FileInput when referencing this file.

  • Name
    mimeType
    Type
    string
    Description

    MIME type of the file (e.g. application/pdf). Use it as the Content-Type header when uploading, and in the FileInput.

  • Name
    expiresInSeconds
    Type
    integer
    Description

    Time in seconds until the upload URL expires.

  • Name
    errors
    Type
    array<string>
    Description

    Array of error messages if any occurred.

cURL
curl --request POST \
  --url 'https://api.autessa.com/clients/managers/generate-file-upload-link?resourceId=V1StGXR8Z5' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: your_api_key' \
  --data '{
    "fileExtension": "pdf"
  }'
JSON
{
  "uploadUrl": "https://s3.amazonaws.com/autessa-files/...",
  "s3Uri": "s3://autessa-files/user-123/file-xyz.pdf",
  "mimeType": "application/pdf",
  "expiresInSeconds": 3600,
  "errors": []
}

WebSocket API​

Streaming Manager Execution WSS/ws/clients/managers/execute​

Real-time manager execution with streaming responses. As the manager works, you receive its reasoning stream, structured sub-agent invocation status updates, and the sub-agents' own streamed output - then a final response.

Connection URL​

wss://api.autessa.com/ws/clients/managers/execute?authorization={key}&resourceId={managerId}

Query Parameters​

  • Name
    authorization
    Type
    string
    Description

    Your API key.

  • Name
    resourceId
    Type
    string
    Description

    The ID of the manager.

  • Name
    conversationId
    Type
    string
    Description

    Optional conversation ID to revive and continue.

  • Name
    versionState
    Type
    string
    Description

    Optional version state override: PUBLISHED (default), DRAFT, or ARCHIVED.

  • Name
    versionNumber
    Type
    integer
    Description

    Optional specific version number to use.

Connection Lifecycle​

  1. Connect - WebSocket connection established; a conversation is created (or revived if conversationId was passed)
  2. Status Message - Server sends conversation status (CREATED, REVIVED, or ERROR)
  3. Send Messages - Client sends MULTIMODAL messages
  4. Receive Streams - Server streams manager reasoning, sub-agent status, and sub-agent output in real time
  5. Final Response - Server sends the complete output for the turn
  6. Disconnect - Connection closes

Voice mode (voiceModeEnabled) is not currently supported on the client Manager WebSocket - it is an Agent API feature. Manager streaming is text/multimodal.

websocat "wss://api.autessa.com/ws/clients/managers/execute?authorization=your_api_key&resourceId=V1StGXR8Z5"

Server-to-Client Status Message​

When you connect, the server immediately sends a status message:

{
  "conversationId": "conv_abc123",
  "status": "CREATED",
  "errors": []
}

Client-to-Server Messages​

Send a JSON message to execute the manager with multimodal input. The conversation ID is managed by the socket session - you don't need to include it.

  • Name
    messageType
    Type
    string
    Description

    "MULTIMODAL" (or its alias "EXECUTE")

  • Name
    managerId
    Type
    string
    Description

    The manager ID. Must match the connection's resourceId.

  • Name
    input
    Type
    array<MultimodalInput>
    Description

    Array of multimodal inputs (text, audio, images, files). See Multimodal Input.

  • Name
    executionOutputMode
    Type
    string
    Description

    "TEXT" or "AUDIO" - desired output format. Defaults to "TEXT".

  • Name
    environmentVariables
    Type
    object
    Description

    Key-value pairs for environment variables that won't be stored on the server.

  • Name
    promptTemplateVariables
    Type
    object
    Description

    Key-value pairs to inject into the manager's prompt template using @@{variableName}@@ syntax.

JSON
{
  "messageType": "MULTIMODAL",
  "managerId": "V1StGXR8Z5",
  "executionOutputMode": "TEXT",
  "input": [
    {
      "inputType": "TEXT",
      "content": "Research our top competitor and draft an outreach email."
    }
  ],
  "promptTemplateVariables": {
    "companyName": "Acme Corp"
  }
}

Streaming Response Messages​

While the manager works, the server streams several kinds of messages. Each message is a JSON object; check which field is present.

1. Manager Text Stream​

The manager's own reasoning and response text, streamed token-by-token:

JSON
{
  "streamedOutput": {
    "outputType": "TEXT",
    "content": " competitor"
  }
}

2. Agent Invocation Status​

Structured updates whenever the manager starts or finishes a sub-agent invocation:

JSON
{
  "agentInvocationStatus": {
    "agentName": "ResearchAgent",
    "agentId": "aB3dE5fG7h",
    "agentInvocationId": "call_abc123",
    "message": "Invoking ResearchAgent...",
    "instruction": "Find the top competitor of Acme Corp"
  }
}

3. Sub-Agent Streamed Output​

The invoked sub-agent's own streaming output (same shape as the Agent API's streaming messages), wrapped with agent identification so you can attribute it:

JSON
{
  "subAgentStreamedOutput": {
    "agentName": "ResearchAgent",
    "agentId": "aB3dE5fG7h",
    "agentInvocationId": "call_abc123",
    "streamedOutput": {
      "outputType": "TEXT",
      "content": "Searching recent filings..."
    }
  }
}

Sub-agent tool activity arrives the same way, as subAgentStreamedOutput.streamedToolMessages.

4. Final Response​

After the orchestration completes (or the manager pauses for your input), the server sends the complete output:

JSON
{
  "output": [
    {
      "outputType": "TEXT",
      "content": "Your top competitor is Globex Inc. Here is the outreach email draft: ..."
    }
  ],
  "waitingForUserInput": false,
  "errors": []
}

If waitingForUserInput is true, send another MULTIMODAL message with the user's answer to continue the same turn.

Custom Version​

Override the default PUBLISHED version of a manager:

  • Name
    versionState
    Type
    string
    Description

    Version state: "PUBLISHED", "DRAFT", or "ARCHIVED". Defaults to "PUBLISHED".

  • Name
    versionNumber
    Type
    integer
    Description

    Specific version number to use (optional).

{
  "managerId": "V1StGXR8Z5",
  "version": {
    "versionState": "DRAFT"
  }
}

Enumerations​

EConversationStatus​

  • IN_PROGRESS - Conversation is active
  • CLOSED - Conversation has been closed
  • NOT_FOUND - Conversation doesn't exist

EManagerLogType​

  • USER_INPUT - User input to the manager
  • MANAGER_REASONING - Manager's reasoning/thinking output
  • MESSAGE_TO_USER - Manager's final message to the user
  • INVOKE_AGENT_REQUEST - Manager invoking a sub-agent
  • INVOKE_AGENT_RESPONSE - Sub-agent invocation result
  • USER_REQUEST - Manager requesting information from the user
  • USER_RESPONSE - User's response to the manager's request

ESubAgentResponseType​

  • COMPLETE - Sub-agent completed the task successfully
  • HELP - Sub-agent needs help or additional information

ExecutionOutputMode​

  • TEXT - Text output (default)
  • AUDIO - Audio output

Rate Limiting​

Manager execution endpoints are rate limited per company and per API key. Rate limit information is included in response headers:

  • X-RateLimit-Limit-Minute - Requests allowed per minute
  • X-RateLimit-Remaining-Minute - Remaining requests this minute
  • X-RateLimit-Limit-Day - Requests allowed per day
  • X-RateLimit-Remaining-Day - Remaining requests today

When rate limited, you'll receive a 429 status code with a Retry-After header.

A manager turn can invoke several sub-agents, each running a full agent conversation with its own tool calls - budget for longer execution times and higher usage than a single-agent request.

Complete Examples​

Multi-Turn Orchestration with Clarification​

JavaScript
const base = 'https://api.autessa.com/clients/managers';
const qs = '?resourceId=V1StGXR8Z5';
const headers = {
  'Content-Type': 'application/json',
  'Authorization': 'your_api_key'
};

// 1. Create conversation
const createResp = await fetch(`${base}/execute-create${qs}`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ managerId: 'V1StGXR8Z5' })
});
const { conversationId } = await createResp.json();

// 2. Execute - the manager may pause with a question
let resp = await fetch(`${base}/execute${qs}`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    managerId: 'V1StGXR8Z5',
    conversationId,
    input: [{ inputType: 'TEXT', content: 'Research our top competitor and draft an outreach email.' }]
  })
});
let data = await resp.json();

// 3. Answer clarifying questions until the manager finishes
while (data.waitingForUserInput) {
  console.log('Manager asks:', data.output[0].content);
  resp = await fetch(`${base}/execute${qs}`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      managerId: 'V1StGXR8Z5',
      conversationId,
      input: [{ inputType: 'TEXT', content: 'Focus on the industrial line.' }]
    })
  });
  data = await resp.json();
}

console.log('Final result:', data.output[0].content);

// 4. Close conversation
await fetch(`${base}/execute-close${qs}`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ managerId: 'V1StGXR8Z5', conversationId })
});

WebSocket Streaming with Sub-Agent Attribution​

JavaScript
const ws = new WebSocket(
  'wss://api.autessa.com/ws/clients/managers/execute?authorization=your_api_key&resourceId=V1StGXR8Z5'
);

let conversationId;

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  // Connection status
  if (data.status) {
    conversationId = data.conversationId;
    ws.send(JSON.stringify({
      messageType: 'MULTIMODAL',
      managerId: 'V1StGXR8Z5',
      executionOutputMode: 'TEXT',
      input: [
        { inputType: 'TEXT', content: 'Research our top competitor and draft an outreach email.' }
      ]
    }));
    return;
  }

  // Manager's own reasoning/response stream
  if (data.streamedOutput) {
    process.stdout.write(data.streamedOutput.content);
  }

  // Structured sub-agent status updates
  if (data.agentInvocationStatus) {
    console.log(`\n[${data.agentInvocationStatus.agentName}] ${data.agentInvocationStatus.message}`);
  }

  // Sub-agent streamed output, attributed by agent
  if (data.subAgentStreamedOutput?.streamedOutput) {
    const sub = data.subAgentStreamedOutput;
    console.log(`\n[${sub.agentName}] ${sub.streamedOutput.content}`);
  }

  // Final response for this turn
  if (data.output) {
    console.log('\nFinal:', data.output[0].content);
    if (data.waitingForUserInput) {
      console.log('Manager is waiting for your answer - send another MULTIMODAL message.');
    }
  }
};