Focused Sessions
A Focused Session is a conversation your application starts, not the user. You hand the assistant a mission (a function, a persona, boundaries, and a completion contract), the assistant works the conversation with your user inside that frame, and when the mission's completion criteria are met your application receives a structured outcome as data.
Use them when the conversation itself is the work:
- A learning app runs a role-play activity graded against a rubric.
- An HR tool conducts a structured screening interview.
- A support portal triages an issue before creating the ticket.
- An onboarding flow gathers the facts your setup wizard needs.
How it differs from the regular assistant
| Assistant | Focused Session | |
|---|---|---|
| Who starts it | The user opens the panel | Your app calls the SDK |
| What it knows | Your whole configured workspace | The mission, plus only what you allow |
| What it can call | All configured tools | Only the tools the mission allows |
| How it ends | It does not | Completion criteria, or your app ends it |
| What you get | A chat transcript | A JSON outcome matching your schema |
Both run on the same assistant, in the same panel, with the same identity and observability. A session is a contract on top of that shared runtime.
The two ways to define a mission
Session Templates (recommended). An administrator authors the mission in
the Backoffice: the prompt (with {{variable}} slots), the allowed tools, the
outcome schema, an optional turn budget. Your page starts the session with the
template id plus variable values. The model-facing text stays under your
organization's control; the page can never inject instructions.
Inline missions (development only). Your page sends the whole mission at start. Handy for prototyping; disabled by default in production deployments because page-supplied prompt text is untrusted input.
When the activity cannot run
A session that needs data from your app to make sense should declare that data
as the template's preflight grounding rather than asking the assistant to
fetch it. Preflight runs before the session exists, so if your backend cannot
supply the data, startFocusedSession rejects and no session is created.
That matters for your UI. You already have a good error state for "this thing is not available right now"; the point of failing at start is that you get to show it, on your page, in your words, instead of the assistant explaining a backend problem to your user inside the chat. Always handle the rejection.
What to do with the outcome
The outcome is AI output. Treat it like any AI-generated artifact: land it in your own review flow, score it, or gate it before it changes user-visible state. Appilot validates it against your schema so the SHAPE is guaranteed; your application decides what it means.
Next: Quick start · API reference