Hosted agent experiences

Overview

The hosted routes provide customer-facing durable experiences without requiring you to build a frontend. Both routes restore server state from cid, resolve supported client tools, expose Continue after interruption, and become read-only after permanent completion.

Use /agent for general agent workflows and document collection. Use /assessment for a focused question-and-answer experience.

Getting started

Start with the deployed assistant ID:

https://chat.amarsia.com/agent/YOUR_DEPLOYMENT_ID
https://chat.amarsia.com/assessment/YOUR_DEPLOYMENT_ID

Both routes understand:

https://chat.amarsia.com/agent/YOUR_DEPLOYMENT_ID?tid=TRIGGER_ID
https://chat.amarsia.com/assessment/YOUR_DEPLOYMENT_ID?cid=CONVERSATION_ID

After a trigger starts a conversation, the route adds cid to the current URL. Keep that resulting URL for refresh, return visits, or another device.

Configuration

Configure the assistant under Tools & Knowledge Base before sharing a route:

Configure hosted ask_user and upload_document flows as always, including trigger links opened later. Use when_connected for custom SDK clients that explicitly advertise the matching capability.

Examples

Email a document request

Configure upload_document as always, then create a trigger:

import { amarsia } from "@amarsia/sdk"

const deploymentId = process.env.AMARSIA_DEPLOYMENT_ID!
const client = amarsia.init({
  apiKey: process.env.AMARSIA_API_KEY!,
  deploymentId,
})

const trigger = await client.trigger.create({
  content: [{ type: "text", text: "Request the signed service agreement." }],
  variables: { CUSTOMER_ID: "cus_123" },
  uiSurface: "agent",
  ttlHours: 72,
})

console.log(`https://chat.amarsia.com/agent/${deploymentId}?tid=${trigger.id}`)

Put the printed link into your email provider. When the recipient opens it, /agent can upload the selected document and resolve the same pending run.

Recover an assessment

Create a trigger with uiSurface: "assessment" and share:

https://chat.amarsia.com/assessment/YOUR_DEPLOYMENT_ID?tid=TRIGGER_ID

The assessment writes cid after start. Reopening the resulting URL restores persisted assistant messages and the current unresolved ask_user call instead of starting again.

Continue an interrupted turn

If a client result was accepted but in-process continuation was interrupted, the hosted UI exposes Continue when the conversation is active and idle. Continue starts a new agent turn using stored conversation history; it does not replay the accepted result.

Hosted behavior

The /agent route:

• Shows actual user and assistant messages, excluding synthetic Start and Continue prompts.
• Shows allowlisted progress types and tool names with safe status summaries.
• Renders the current ask_user or upload_document card.
• Leaves unknown custom tools pending for a capable custom client.

The /assessment route:

• Shows assistant messages only.
• Renders only the current ask_user call.
• Hides general activity and document-upload UI.

Both routes use SDK-managed refresh, stop local refresh when the page closes, disable writes after completion, and preserve server state for the next open.

Security

Enable Trigger required when only prepared sessions should start. Trigger expiry controls an unused trigger; after use, cid restores the linked conversation.

Configure authentication and origin allowlists for your deployment. Treat URLs containing tid or cid as application data: send them only to intended recipients and avoid analytics that capture full query strings.

Related

• Durable agent conversations
• Client tools
• Agent SDK and React
• Trigger API