Skip to main content

Managers

A manager is a multi-agent orchestrator: instructions, a model, and a set of sub-agents it delegates to. Where an agent calls tools, a manager calls agents. You configure and publish one from the terminal exactly as you would an agent — but you cannot run one here, which is the single most important thing to know about this namespace.

There is no managers execute. Managers are run only by hosted apps and end-user clients. The conversations and statistics you read here reflect those external runs, never a run you started from the CLI. Attempting it fails with Unknown command 'managers execute'.

Key concepts​

The delegation hierarchy​

   manager                 instructions + model + sub-agents
      │  delegates to
      ▼
   agent                   instructions + model + tools
      │  calls
      ▼
   tool                    one capability (LLM_CALL, AUTESSADB_QUERY_TABLE, …)

Each layer attaches the one below it by id, and each has its own draft/published lifecycle. Build bottom-up: tools first, then the agents that use them, then the manager that routes between those agents.

Draft and published​

A manager has a draft (your working copy) and a published version. create and update write the draft; publish snapshots it as a new live version. Because managers are only ever invoked externally, publishing is what makes your changes reachable at all — an unpublished manager is inert.

The SDK creates SIMPLE managers only​

managerType is required on create and must be SIMPLE. As with agents, the CLI can read, update, share and manage managers of any type that already exists.

Sub-agents must exist and be published​

Every agent you reference must exist in the same company. Changing the agents list rebuilds the manager's agent set wholesale — it is not additive.

How to create a manager​

autessa managers create \
  --managerType SIMPLE \
  --managerName "Support Router" \
  --managerDescription "Routes an inbound support request to the right specialist agent."
{
  "manager": {
    "managerId": "oXfsm9U2z4a",
    "managerType": "SIMPLE",
    "name": "Support Router",
    "description": "Routes an inbound support request to the right specialist agent.",
    "instructions": "Coordinate and manage the agents to accomplish the task",
    "model": "SMALL_INSTRUCTION_FOLLOWING",
    "maxIterations": 30,
    "agents": [],
    "voiceConfig": { "voiceModel": "SMALL", "voiceName": "FEMALE" },
    "promptTemplateVariables": {},
    "evaluationNotes": "",
    "tags": []
  }
}

Like an agent, a fresh manager arrives with placeholder instructions, a default model, no sub-agents, and maxIterations: 30.

managerDescription is required, unlike an agent's description. Write it as a real statement of what the manager routes — it is what a human picks it by in the manager list.

How to attach sub-agents​

managers update takes the complete desired configuration in --updatedManager, so read-modify-submit rather than sending a patch. Sub-agents attach by id alone — the server hydrates the rest:

autessa managers update --managerId oXfsm9U2z4a --updatedManager '{
  "managerId": "oXfsm9U2z4a",
  "managerType": "SIMPLE",
  "name": "Support Router",
  "description": "Routes an inbound support request to the right specialist agent.",
  "instructions": "Read the request and delegate: billing questions to billing_agent, technical faults to triage_agent. Return the specialist'"'"'s answer without rewriting it.",
  "model": "SMALL_INSTRUCTION_FOLLOWING",
  "maxIterations": 10,
  "agents": [
    { "agentId": "ykWFTe6UF56h" },
    { "agentId": "K2UYSwk3Yy4i" }
  ]
}'

The response echoes each sub-agent fully expanded — its instructions, model, and its own attached tools — so you can confirm the routing set is what you intended:

{
  "updatedManager": {
    "managerId": "oXfsm9U2z4a",
    "maxIterations": 10,
    "agents": [
      {
        "agentId": "ykWFTe6UF56h",
        "agentType": "SIMPLE",
        "name": "billing_agent",
        "description": "Answers billing questions.",
        "agentInstructions": "You are a professional agent who does as asked.",
        "model": "SMALL_INSTRUCTION_FOLLOWING",
        "tools": [],
        "maxIterations": 30
      }
    ],
    "instructions": "Read the request and delegate: billing questions to billing_agent, ...",
    "model": "SMALL_INSTRUCTION_FOLLOWING"
  }
}

The fields worth deliberate thought:

FieldWhat it controls
instructionsThe orchestration prompt — how it decides which sub-agent handles what. Name the agents explicitly.
agentsThe sub-agents it may delegate to, by id. Replaces the whole set.
modelThe tier the manager reasons with when routing. Sub-agents keep their own models.
maxIterationsOrchestration rounds per turn. A router that hands off once needs far fewer than 30.
promptTemplateVariablesNamed slots the instructions reference
voiceConfigVoice model and name, when voice-enabled
A sub-agent's own name and description drive routing quality the way a tool's name and description drive an agent's tool choice. If a manager delegates to the wrong agent, fix that agent's description before rewriting the manager's instructions.

Voice options​

managers get returns the voice choices valid for the manager's model alongside the configuration, so you do not have to guess a voiceName:

autessa managers get --managerId oXfsm9U2z4a
{
  "manager": { "...": "..." },
  "permission": "ADMIN",
  "voiceOptionsList": [
    {
      "voiceModel": "SMALL",
      "voices": { "builtInVoiceNames": ["FEMALE", "MALE"], "customVoiceNames": [] }
    }
  ]
}

customVoiceNames lists your company's voice clones — see Custom voices.

How to publish​

autessa managers publish --managerId oXfsm9U2z4a
{ "publishedManagerVersion": 1 }
autessa managers versions --managerId oXfsm9U2z4a
autessa managers rollback --managerId oXfsm9U2z4a --json '{...}'

versions lists the published version (null if never published) and every archived one; rollback re-publishes an archived version, archiving the current one in its place. See Versions.

How to read what happened​

Since you cannot start a run here, this is where most of your time in the namespace goes.

autessa managers conversations --managerId oXfsm9U2z4a --page 0
{
  "conversations": [],
  "totalElements": 0,
  "totalPages": 0,
  "currentPage": 0,
  "pageSize": 50,
  "hasNext": false,
  "hasPrevious": false
}

An empty result on a working manager usually means one of two things: nobody has run it yet through an app or client, or the runs that exist are your own sandbox sessions from the web UI. Two flags matter here:

FlagEffect
--includeMySandboxConversationsInclude your own UI/sandbox conversations alongside API-key ones. Reach for this first when the list looks empty.
--expandAgentsInline each sub-agent's full context into the orchestration log, so you can see what the delegate actually did rather than just that it was called.

Listings are trimmed by default so a page stays under the response size limit — --full returns complete transcripts instead of metadata.

autessa managers conversations --managerId oXfsm9U2z4a \
  --includeMySandboxConversations --expandAgents --full

For one conversation with its complete orchestration log:

autessa managers conversation --managerId oXfsm9U2z4a --conversationId <id>

The same data backs Manager history in the web app. Tool calls made by sub-agents during a manager run also land in tool history tagged source: "AGENT" — see Tools.

How to evaluate​

autessa managers submit-evaluation \
  --managerId oXfsm9U2z4a \
  --conversationId <id> \
  --humanEvaluation '{"status":"SUCCESSFUL","notes":"Routed to the right specialist."}'

autessa managers statistics \
  --managerId oXfsm9U2z4a \
  --startDate 2026-09-01T00:00:00 \
  --endDate 2026-09-30T23:59:59
The date form is strict: yyyy-MM-ddTHH:mm:ss with no zone. A trailing Z, a numeric offset, or a bare date are all rejected with a schema error. The value is interpreted as UTC. Agent statistics take the same form.

How to share and delete​

autessa managers get-sharing-details --managerId oXfsm9U2z4a

autessa managers share --managerId oXfsm9U2z4a --level COMPANY --accessLevel READ

autessa managers share --managerId oXfsm9U2z4a --level SPECIFIC_MEMBER \
  --usersToAdd '[{"userEmail":"teammate@example.com","accessLevel":"WRITE"}]'

Same sharing model as agents, tools and tables.

autessa managers delete --managerId oXfsm9U2z4a

Deletion is permanent and also revokes the manager's API-key permission — any app or client invoking it stops working immediately. The sub-agents themselves are untouched.

Full command reference​

17 commands17 runnable
CommandWhat it does
autessa managers conversationFetch one closed manager conversation by conversationId, including its full orchestration log and evaluations.
autessa managers conversationsList a manager's closed conversations, newest first, one fixed-size page at a time (page is 0-based).
autessa managers createCreate a new draft manager with a name and description.
autessa managers deletePermanently delete a manager and revoke its API-key permission.
autessa managers generate-audio-upload-linkGenerate a presigned S3 PUT URL for uploading a WAV audio file to reference in a manager conversation.
autessa managers generate-file-upload-linkGenerate a presigned S3 PUT URL for a transient document attachment to reference in a manager conversation.
autessa managers generate-image-upload-linkGenerate a presigned S3 PUT URL for uploading an image (png, jpg, jpeg) to reference in a manager conversation.
autessa managers getFetch a single manager by id, including its full configuration (sub-agents, instructions, model, voice), your access level, and the voice options for its model.
autessa managers get-allList every manager you can access in the current company, split into three buckets — managers you own, managers shared company-wide, and managers shared specifically with you.
autessa managers get-sharing-detailsGet a manager's sharing configuration — sharing level, company-wide permission, per-user grants, and your own access level.
autessa managers publishPublish the manager's current draft as a new live version.
autessa managers rollbackRe-publish a previously archived manager version, archiving the currently published version in its place.
autessa managers shareSet a manager's sharing mode — PRIVATE, COMPANY-wide at one access level, or SPECIFIC_MEMBER with per-user grants via usersToAdd/usersToRemove.
autessa managers statisticsCompute aggregate evaluation statistics for a manager's conversations closed within a date range.
autessa managers submit-evaluationRecord a HUMAN evaluation — a human-in-the-loop verdict plus notes — on a stored manager conversation, looked up by conversationId.
autessa managers updateUpdate a manager by submitting its modified configuration in updatedManager.
autessa managers versionsList a manager's version numbers — the currently published version (null if never published) and all archived versions.