Agents

An agent is instructions, a model, and a set of tools it may call. Building one from the terminal is create → configure → publish, and running one is either a single-pass execute or a multi-turn conversation you open, drive and close. Every command and response on this page is real output from a live session.

An agent's capabilities are its tools, and a tool has to exist and be published before you can attach it. If you have not built one yet, start with Tools — that page covers picking a tool type, configuring it, and testing it in isolation.

Key concepts

Draft and published are different things

An agent has a draft (your working copy) and a published version (what actually runs). create and update write the draft; publish snapshots it as a new live version.

Publish before the agent serves anything beyond your own test executions — scheduled jobs, hosted apps and end-user clients all run the published version.

The SDK creates SIMPLE agents only

agentType is required on create and must be SIMPLE. The CLI can read, update, run, share and manage agents of any type that already exists — the restriction is only on what it creates.

Tools attach by id

Adding a capability means putting a tool's id in the agent's tools array. The tool must already be published; see Tools. Creating and publishing a tool does not attach it to anything on its own.

How to create an agent

autessa agents create \
  --agentType SIMPLE \
  --agentName "Summarizer" \
  --agentDescription "Summarizes text on request."

{
  "agent": {
    "agentId": "K2UYSwk3Yy4i",
    "agentType": "SIMPLE",
    "name": "Summarizer",
    "description": "Summarizes text on request.",
    "agentInstructions": "You are a professional agent who does as asked.",
    "model": "SMALL_INSTRUCTION_FOLLOWING",
    "maxIterations": 30,
    "tools": [],
    "voiceConfig": { "voiceModel": "SMALL", "voiceName": "FEMALE" },
    "promptTemplateVariables": {},
    "evaluationNotes": "",
    "tags": [],
    "enableBrowserTools": false
  }
}

A fresh agent arrives with placeholder instructions, a default model, no tools, and maxIterations: 30. All of that is yours to change with update.

How to attach tools and write the instructions

Like tools update, agents update takes the full desired configuration in --updatedAgent, so read-modify-submit rather than sending a patch. Attaching a tool needs only its id — the server hydrates the rest:

autessa agents update --agentId K2UYSwk3Yy4i --updatedAgent '{
  "agentId": "K2UYSwk3Yy4i",
  "agentType": "SIMPLE",
  "name": "Summarizer",
  "description": "Summarizes text on request.",
  "agentInstructions": "You summarize text for the user. Always call the summarize_text tool to produce the summary, then reply with just that sentence.",
  "model": "SMALL_INSTRUCTION_FOLLOWING",
  "maxIterations": 10,
  "tools": [{ "toolId": "gPdJwp5jbr9eN" }]
}'

The response echoes the agent with each tool fully expanded — its type, config and arguments — so you can confirm you attached the thing you meant to.

The fields worth deliberate thought:

Field	What it controls
agentInstructions	The system prompt. Name the tools you expect it to call and when.
model	Capability tier by alias — SMALL_INSTRUCTION_FOLLOWING, BIG_INSTRUCTION_FOLLOWING, BIG_INSTRUCTION_FOLLOWING_REASONING, VIBE_CODING, AUTESSA_120B
maxIterations	How many tool-calling rounds before the agent must answer. Too low truncates multi-step work; too high lets a confused agent burn executions.
tools	The capabilities it may call, by id
promptTemplateVariables	Named slots you fill per run
enableBrowserTools	Whether it gets browser capabilities

A tool's own toolName and toolDescription do more for reliability than the agent's instructions — the model reads those to decide when to call it. If an agent picks the wrong tool, fix the tool's description before rewriting the prompt.

How to publish

autessa agents publish --agentId K2UYSwk3Yy4i

{ "publishedAgentVersion": 1 }

How to run an agent

One-shot

Omit conversationId for a single-pass run:

autessa agents execute \
  --agentId K2UYSwk3Yy4i \
  --messageType MULTIMODAL \
  --input '[{"inputType":"TEXT","content":"Summarize: the Autessa CLI is generated from the live SDK manifest, so commands are discovered with help rather than memorized, and everything it does is visible in the web builder immediately."}]'

{
  "output": [
    {
      "content": "The Autessa CLI is generated from the live SDK manifest, making commands discoverable through help instead of memorization, with all actions instantly visible in the web builder.",
      "outputType": "TEXT"
    }
  ]
}

--messageType MULTIMODAL is the ordinary text execution. The other message types do not run the agent at all: VOICE is the handshake that opens a live voice session, and PLAYBACK_COMPLETE is a telephony client reporting audio playback progress.

--input is an array of parts, so text, images, files and audio can be mixed. TEXT carries content; IMAGE/FILE carry s3Uri and mimeType; AUDIO carries base64EncodedData and audioFormat. Presigned upload URLs come from agents generate-image-upload-link, generate-file-upload-link and generate-audio-upload-link.

Multi-turn

Open a conversation, drive it, then close it:

CID=$(autessa agents execute-create --agentId K2UYSwk3Yy4i | jq -r '.conversationId')

autessa agents execute \
  --agentId K2UYSwk3Yy4i \
  --conversationId "$CID" \
  --messageType MULTIMODAL \
  --input '[{"inputType":"TEXT","content":"Summarize: autessa login opens a browser, you pick a company, and the CLI stores a tenant-scoped session credential."}]'

{
  "output": [
    {
      "content": "`autessa login` opens a browser for company selection, then stores a tenant-scoped session credential in the CLI.",
      "outputType": "TEXT"
    }
  ]
}

autessa agents execute-close --agentId K2UYSwk3Yy4i --conversationId "$CID"

Closing a conversation is what commits it to history. An open conversation is not yet in conversations history, and logging happens asynchronously after the close — so allow a moment before reading it back.

Hidden inputs

--environmentVariables passes values into the agent's tools for a turn without ever showing them to the model — secrets, API keys, or per-caller context a tool needs but the model must not see or invent. --promptTemplateVariables fills the agent's declared template slots. See Environment variables.

Running a specific version

By default execute runs the published version. Target another with --version:

autessa agents execute --agentId K2UYSwk3Yy4i \
  --version '{"versionState":"PUBLISHED","versionNumber":2}' \
  --messageType MULTIMODAL \
  --input '[{"inputType":"TEXT","content":"..."}]'

autessa agents versions --agentId <id> lists the published and archived version numbers, and agents rollback re-publishes an archived one. See Versions.

How to read conversation history

autessa agents conversations history --agentId K2UYSwk3Yy4i --page 0

autessa agents conversations conversation \
  --agentId K2UYSwk3Yy4i \
  --conversationId f719af72-2e49-462e-a98c-63011a5a5671

conversation returns the full message and tool log for one closed conversation, plus its version and any evaluations. The same data backs Agent history in the web app.

To see the individual tool calls an agent made — with their decrypted inputs and outputs — read the tool side instead, where agent-driven runs are tagged source: "AGENT":

autessa tools history list --toolId gPdJwp5jbr9eN

See Tools.

How to evaluate

autessa agents submit-evaluation \
  --agentId K2UYSwk3Yy4i \
  --conversationId f719af72-2e49-462e-a98c-63011a5a5671 \
  --humanEvaluation '{"status":"SUCCESSFUL","notes":"Correct summary, one tool call."}'

autessa agents statistics \
  --agentId K2UYSwk3Yy4i \
  --startDate 2026-09-01T00:00:00 \
  --endDate 2026-09-30T23:59:59

submit-evaluation records a human verdict and notes on a stored conversation — run autessa agents submit-evaluation help for the full list of verdict values, which distinguish "succeeded" from "succeeded inefficiently". statistics aggregates success and failure counts across a date range, broken down by version.

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.

How to share and delete

autessa agents get-sharing-details --agentId K2UYSwk3Yy4i

autessa agents share --agentId K2UYSwk3Yy4i --level COMPANY --accessLevel READ

autessa agents share --agentId K2UYSwk3Yy4i --level SPECIFIC_MEMBER \
  --usersToAdd '[{"userEmail":"teammate@example.com","accessLevel":"WRITE"}]'

Sharing modes are PRIVATE, COMPANY at one access level, or SPECIFIC_MEMBER with per-user grants — the same shape tools and tables use.

autessa agents delete --agentId K2UYSwk3Yy4i

Deletion is permanent: the agent, its draft and every version go with it. The tools it referenced are untouched.

Full command reference

20 commands20 runnable

Command	What it does
autessa agents all	List every agent you can access in the current company, split into three buckets — agents you own, agents shared company-wide, and agents shared specifically with you.
autessa agents conversations conversation	Fetch one closed agent conversation by conversationId, including its full message/tool log, version, and evaluations.
autessa agents conversations history	List an agent's closed conversations, newest first, one fixed-size page at a time (page is 0-based).
autessa agents create	Create a new draft SIMPLE agent with a name and description.
autessa agents delete	Permanently delete an agent, its draft, and all its versions.
autessa agents execute	Send a message to an agent and receive its multimodal reply (bills one agent execution).
autessa agents execute-close	Close an open agent conversation.
autessa agents execute-create	Open a new multi-turn conversation with an agent and get its conversationId.
autessa agents generate-audio-upload-link	Generate a presigned S3 PUT URL for uploading a WAV audio file.
autessa agents generate-file-upload-link	Generate a presigned S3 PUT URL for a PER-EXECUTION transient document attachment (pdf, docx, xlsx, pptx, txt, json, yaml, xml, html, csv, md).
autessa agents generate-image-upload-link	Generate a presigned S3 PUT URL for uploading an image (png, jpg, jpeg).
autessa agents get	Fetch a single agent by id, including its full configuration and your access level.
autessa agents get-sharing-details	Get an agent's sharing configuration — sharing level, company-wide permission, per-user grants, and your own access level.
autessa agents publish	Publish the agent's current draft as a new live version.
autessa agents rollback	Re-publish a previously archived agent version, archiving the currently published version in its place.
autessa agents share	Set an agent's sharing mode — PRIVATE, COMPANY-wide at one access level, or SPECIFIC_MEMBER with per-user grants via usersToAdd/usersToRemove.
autessa agents statistics	Compute aggregate evaluation statistics (success/failure counts, per-version breakdown) for an agent's conversations closed within a date range.
autessa agents submit-evaluation	Record a HUMAN evaluation — a human-in-the-loop verdict plus notes — on a stored agent conversation, looked up by conversationId.
autessa agents update	Update an agent by submitting its modified configuration in updatedAgent.
autessa agents versions	List an agent's version numbers — the currently published version (null if never published) and all archived versions.

Related

• Tools — build the capabilities you attach here
• Managers — orchestrate several agents
• Scheduled jobs — run an agent on a timer
• Agents in the builder
• Agent history
• Autessa CLI