autessa.agents
Create, configure, publish, and run agent conversations.
autessa.agents.allREAD
autessa.agents.all()List every agent you can access in the current company.
Returns your accessible agents split into three buckets: agents you own, agents shared company-wide, and agents shared specifically with you. Not paginated.
Request fields
No fields.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
ownedAgents- Type
- AutessaAgent[]
- Description
- Name
companySharedAgents- Type
- AutessaAgent[]
- Description
- Name
sharedWithMeAgents- Type
- AutessaAgent[]
- Description
autessa.agents.conversations.conversationREAD
autessa.agents.conversations.conversation({ agentId, conversationId })Fetch one closed agent conversation by conversationId, including its full message log, version, and evaluations.
The conversation must belong to the given agent and your company. Read-only; sandbox (UI-created) conversations report apiKeyId my-sandbox.
Request fields
- Name
agentId- Type
- string (opaque id)
- Description
- References agent by opaque id.
- Name
conversationId- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
conversation- Type
- AgentConversationDto
- Description
autessa.agents.conversations.historyREAD
autessa.agents.conversations.history({ agentId, page, includeMySandboxConversations })List an agent's closed conversations, newest first, one fixed-size page at a time (page is 0-based).
By default only API-key conversations are returned; set includeMySandboxConversations true to include your own sandbox runs. Continue paging by hasNext/totalPages: conversations with unparseable logs are dropped after pagination, so a short or empty page does not mean the end.
Request fields
- Name
agentId- Type
- string (opaque id)
- Description
- References agent by opaque id.
- Name
page- Type
- number
- Description
- Name
includeMySandboxConversations- Type
- boolean
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
conversations- Type
- AgentConversationDto[]
- Description
- Name
totalElements- Type
- number
- Description
- Name
totalPages- Type
- number
- Description
- Name
currentPage- Type
- number
- Description
- Name
pageSize- Type
- number
- Description
- Name
hasNext- Type
- boolean
- Description
- Name
hasPrevious- Type
- boolean
- Description
autessa.agents.createMUTATE
autessa.agents.create({ agentType, agentName, agentDescription })Create a new SIMPLE agent with a name and description.
Creates a draft SIMPLE agent — the SDK only creates SIMPLE agents. Configure its instructions, tools, and voice via agents.update, then agents.publish to make it live. agentType is required and must be SIMPLE (explicit by design), and it cannot be changed afterwards. The SDK can read, update, run, and manage agents of any type that already exist, but SIMPLE is the only type it creates. To give a SIMPLE agent document search, attach a semantic-query search tool to it via agents.update (see the grounding-agent-on-documents guide). Browser tools can only be enabled from the agent settings page in the browser UI — the SDK cannot enable them on create or update.
Request fields
- Name
agentType- Type
- "SIMPLE"
- Description
- Name
agentName- Type
- string
- Description
- Name
agentDescription- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
agent- Type
- AutessaAgent
- Description
autessa.agents.deleteMUTATE
autessa.agents.delete({ agentId })Permanently delete an agent.
Irreversible. Deletes the agent, its draft and all versions. Requires ADMIN access.
Request fields
- Name
agentId- Type
- string (opaque id)
- Description
- References agent by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
autessa.agents.executeMUTATE
autessa.agents.execute({ agentId, messageType, version, conversationId, input, environmentVariables, promptTemplateVariables, executionOutputMode })Send a message to an agent conversation and receive the agent's reply (bills agent execution).
Sends multimodal input into the conversation opened by agents.executeCreate and returns the agent's multimodal output. Bills one agent execution. Pass conversationId to continue an existing conversation.
Request fields
- Name
agentId- Type
- string (opaque id)
- Description
- References agent by opaque id.
- Name
messageType- Type
- "VOICE" | "MULTIMODAL" | "PLAYBACK_COMPLETE"
- Description
- Name
version- Type
- CustomVersion
- Description
- Name
conversationId- Type
- string
- Description
- Name
input- Type
- MultimodalInput[]
- Description
- Name
environmentVariables- Type
- object
- Description
- Name
promptTemplateVariables- Type
- object
- Description
- Name
executionOutputMode- Type
- "TEXT" | "AUDIO"
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
output- Type
- MultimodalOutput[]
- Description
- Name
streamedToolMessages- Type
- ExecuteToolResponse
- Description
- Name
streamedOutput- Type
- MultimodalOutput
- Description
- Name
agentName- Type
- string
- Description
- Name
agentId- Type
- string
- Description
- Name
agentInvocationId- Type
- string
- Description
- Name
criticStreamingStage- Type
- "INITIAL" | "RETRY_1" | "RETRY_2" | "RETRY_3" | "APPROVED" | "REJECTED"
- Description
- Name
localToolRequest- Type
- AgentExecuteToolRequest
- Description
autessa.agents.executeCloseMUTATE
autessa.agents.executeClose({ agentId, conversationId })Close an open agent conversation.
Ends the conversation opened by agents.executeCreate; the conversation is then readable via agents.conversations.conversation and agents.conversations.history.
Request fields
- Name
agentId- Type
- string (opaque id)
- Description
- References agent by opaque id.
- Name
conversationId- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
autessa.agents.executeCreateMUTATE
autessa.agents.executeCreate({ agentId })Open a new conversation with an agent and get its conversation id.
Start here before agents.execute: the returned conversationId threads subsequent messages into one conversation. Close it with agents.executeClose when done.
Request fields
- Name
agentId- Type
- string (opaque id)
- Description
- References agent by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
conversationId- Type
- string
- Description
autessa.agents.generateAudioUploadLinkMUTATE
autessa.agents.generateAudioUploadLink()Generate a presigned S3 PUT URL for uploading a WAV audio file; PUT the bytes there, then pass the returned s3Uri into an agent or tool execution.
The URL expires in 300 seconds and targets temporary storage — upload and use the s3Uri promptly.
Request fields
No fields.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
uploadUrl- Type
- string
- Description
- Name
s3Uri- Type
- string
- Description
- Name
expiresInSeconds- Type
- number
- Description
autessa.agents.generateFileUploadLinkMUTATE
autessa.agents.generateFileUploadLink({ fileExtension })Generate a presigned S3 PUT URL for a PER-EXECUTION transient document attachment (pdf, docx, xlsx, pptx, txt, json, yaml, xml, html, csv, md); PUT the bytes there, then pass the returned s3Uri into a SINGLE agent/tool execution. NOT a way to give an agent durable knowledge.
ANTI-PATTERN WARNING: this is a temporary per-run attachment, NOT knowledge or grounding. The URL expires in 300 seconds and the bytes target temporary storage, so the document is available for ONE execution only — it does not persist and the agent cannot retrieve it on a later run. To GROUND an agent on documents it can search across conversations, do NOT use this: instead put the (chunked) text into an AutessaDB table with a vectorized column and attach an AUTESSADB_SEMANTIC_QUERY tool to the agent (see the 'Grounding an agent on documents' guide). Send fileExtension explicitly — an unrecognized or missing extension silently defaults to pdf.
Request fields
- Name
fileExtension- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
uploadUrl- Type
- string
- Description
- Name
s3Uri- Type
- string
- Description
- Name
mimeType- Type
- string
- Description
- Name
expiresInSeconds- Type
- number
- Description
autessa.agents.generateImageUploadLinkMUTATE
autessa.agents.generateImageUploadLink({ fileExtension })Generate a presigned S3 PUT URL for uploading an image (png, jpg, jpeg); PUT the bytes there, then pass the returned s3Uri into an agent or tool execution.
Send fileExtension explicitly — an unrecognized or missing extension silently defaults to png. The URL expires in 300 seconds and targets temporary storage.
Request fields
- Name
fileExtension- Type
- string
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
uploadUrl- Type
- string
- Description
- Name
s3Uri- Type
- string
- Description
- Name
mimeType- Type
- string
- Description
- Name
expiresInSeconds- Type
- number
- Description
autessa.agents.getREAD
autessa.agents.get({ agentId, version })Fetch a single agent by id, including its full configuration and your access level.
Returns the agent entity, your permission on it, and the available voice options. Pass version to read a specific published or archived version instead of the draft.
Request fields
- Name
agentId- Type
- string (opaque id)
- Description
- References agent by opaque id.
- Name
version- Type
- CustomVersion
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
permission- Type
- "READ" | "WRITE" | "PUBLISH" | "ADMIN"
- Description
- Name
agent- Type
- AutessaAgent
- Description
- Name
voiceOptionsList- Type
- VoiceOptions[]
- Description
autessa.agents.getSharingDetailsREAD
autessa.agents.getSharingDetails({ agentId })Get an agent's sharing configuration: sharing level, company-wide permission, per-user grants, and your own access level.
Read-only view of exactly what agents.share would modify.
Request fields
- Name
agentId- Type
- string (opaque id)
- Description
- References agent by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
sharingLevel- Type
- "PRIVATE" | "SPECIFIC_MEMBER" | "COMPANY"
- Description
- Name
companyPermissionLevel- Type
- "READ" | "WRITE" | "PUBLISH" | "ADMIN"
- Description
- Name
sharedWith- Type
- UserShareWrapper[]
- Description
- Name
userAccessLevel- Type
- "READ" | "WRITE" | "PUBLISH" | "ADMIN"
- Description
autessa.agents.publishMUTATE
autessa.agents.publish({ agentId })Publish the agent's current draft configuration as a new live version.
Snapshots the draft into a new immutable, published version. Requires PUBLISH or ADMIN access. Returns the new published version number.
Request fields
- Name
agentId- Type
- string (opaque id)
- Description
- References agent by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
publishedAgentVersion- Type
- number
- Description
autessa.agents.rollbackMUTATE
autessa.agents.rollback({ agentId, versionToRollback })Re-publish a previously archived agent version, archiving the currently published version in its place.
versionToRollback must be an archived version number from agents.versions, and a published version must already exist. This swaps versions rather than minting a new one; the unpublished draft is untouched. Requires PUBLISH or ADMIN access.
Request fields
- Name
agentId- Type
- string (opaque id)
- Description
- References agent by opaque id.
- Name
versionToRollback- Type
- number
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
newPublishedVersion- Type
- number
- Description
autessa.agents.statisticsREAD
autessa.agents.statistics({ agentId, startDate, endDate })Compute aggregate evaluation statistics (success/failure counts, per-version breakdown) for an agent's conversations closed within a date range.
agentId and startDate are required; endDate defaults to now. Synchronous and heavy — it decrypts and parses every conversation log in the range, so keep date windows narrow.
Request fields
- Name
agentId- Type
- string (opaque id)
- Description
- References agent by opaque id.
- Name
startDate- Type
- string (ISO 8601)
- Description
- Name
endDate- Type
- string (ISO 8601)
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
statistics- Type
- AgentStatistics
- Description
autessa.agents.submitEvaluationMUTATE
autessa.agents.submitEvaluation({ agentId, conversationId, humanEvaluation })Attach or replace a human evaluation (status plus notes) on a stored agent conversation, looked up by conversationId.
humanEvaluation.status is one of SUCCESSFUL, SUCCESSFUL_NOT_EFFICIENT, SUCCESSFUL_NOT_ALL_STEPS, UNSUCCESSFUL. Overwrites any existing human evaluation without confirmation; the agentId request field is ignored — only conversationId matters.
Request fields
- Name
agentId- Type
- string (opaque id)
- Description
- References agent by opaque id.
- Name
conversationId- Type
- string
- Description
- Name
humanEvaluation- Type
- HumanEvaluation
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
autessa.agents.updateMUTATE
autessa.agents.update({ agentId, updatedAgent })Update an agent by submitting its modified configuration in updatedAgent (read with agents.get, modify, submit).
The submitted updatedAgent is overlaid onto the stored configuration — always start from the entity returned by agents.get so unmentioned fields survive. This is where you GIVE THE AGENT ITS TOOLS: an agent can only use tools present in its updatedAgent.tools array, so to add a capability, append the tool (from tools.get / tools.all — only toolId is load-bearing) to that array here, then call agents.publish so the change goes live. Creating or publishing a tool alone does NOT attach it to any agent; attachment happens only through this update. Two fields cannot be changed through the SDK and are not part of the update request shape: agentType (an agent's type is fixed; re-typing is a browser-UI operation) and enableBrowserTools (browser tools can only be enabled from the agent settings page in the browser UI). Both keep their stored values regardless of what you submit. Agents of any type can be updated this way; only re-typing and enabling browser tools are excluded.
Request fields
- Name
agentId- Type
- string (opaque id)
- Description
- References agent by opaque id.
- Name
updatedAgent- Type
- AutessaAgentUpdate
- Description
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
updatedAgent- Type
- AutessaAgent
- Description
autessa.agents.versionsREAD
autessa.agents.versions({ agentId })List an agent's version numbers: the currently published version (null if never published) and all archived versions.
Use archivedVersions with agents.rollback to re-publish an older version.
Request fields
- Name
agentId- Type
- string (opaque id)
- Description
- References agent by opaque id.
Response fields
- Name
errors- Type
- string[]
- Description
- Name
deprecationWarnings- Type
- string[]
- Description
- Name
sessionToken- Type
- string
- Description
- Name
currentPublishedVersion- Type
- number
- Description
- Name
archivedVersions- Type
- number[]
- Description