Agentic Sessions

Crafting has built-in agent workers and manages the conversations between users and LLM agents as first-class objects in the system. Users can list and inspect the details of all conversations.

Session Types

In Crafting, a session is referenced as one of the following types:

Conversation — an interactive conversation started from the Agentic UI or the CLI. When the session is completed, follow-up messages can be entered to resume it. Conversations are owned by the user who starts them and are not shared across the org, although org admins are able to list all conversations across the org.
Autonomous Task — a non-interactive, task-oriented conversation. It is automatically archived when it completes and does not accept follow-ups. By default, autonomous tasks are shared across the org. They can be accessed via Automation / AI Tasks from the Full Web Console.
Ad-hoc Chat — a chat initiated from the Chat menu embedded in the Web UI.

Both Conversation and Autonomous Task have full lifecycle ownership of the resources created from the session. For example, sandboxes and child sessions created during the session share the same lifecycle as the session, so they are deleted automatically when the session is either archived or deleted.

An Ad-hoc Chat has no lifecycle ownership of the resources created during the session. A sandbox created from an ad-hoc chat is left over when the session is deleted.

Archiving

Archiving is an operation that releases the resources created during a session while keeping the original conversation for future reference. It is often used to control cost, and is the default for Autonomous Tasks, which may start at large scale.

For Conversations, there is a configuration in LLM that can specify automated archiving if the session stays idle for a period of time.

An archived session is read-only and can no longer be resumed.

How to Use

Start

A Conversation can be kicked off from the Agentic UI. An Ad-hoc Chat can be started from the floating chat button in the Full Web Console.

A session — either a Conversation or an Autonomous Task — can also be started programmatically using the CLI:

cs llm session run --task --name NAME --agent AGENT PROMPT|-|@FILE

The command above starts an Autonomous Task session with the name NAME.

--agent AGENT specifies an AI Agent defined in the org (use my:AGENT for an agent defined personally). This flag is optional; if unspecified, the Default Agent is used.
With the flag --interactive, the session becomes a Conversation, which disables automatic archiving upon completion of the session.
The initial prompt can be passed as command line arguments, from stdin (use - as the argument), or from a file (use @FILE).

Limit Templates

If only a set of templates may be used by the agent in an autonomous session, use the flag --allow-template PATTERN|re:REGEXP. For example:

cs llm session run --task --name foo --allow-template 'agent-*' --allow-template 're:-agent-.*' prompt

If a certain set of templates should be excluded from being used by the agent, use the flag --exclude-template PATTERN|re:REGEXP. The flag --exclude-template is applied after --allow-template. If no --allow-template is specified, --exclude-template is applied to all available templates.

cs llm session run --task --name foo --exclude-template 'legacy-*' --exclude-template 're:-internal-.*' prompt

Impersonation

When run by an org admin (or a service account with the Admin role), the session can be created as owned by another user. For example:

cs llm session run --task --name=jacky-request-1135 --owner=jacky@example.com ...

Use with caution: the session is owned by jacky@example.com, not the user who ran the command. All resources (e.g. sandboxes) created later will also be owned by jacky@example.com.

This is different from specifying an initiator, which is informational only. For example:

cs llm session run --task --name=alice-request-2519 --initiator=alice@example.com ...

The session is owned by the user who ran the command, as are all resources created during the session. The email alice@example.com is recorded purely as the initiator, and it does not even need to be a valid member of the current org.

Default Agent

If no agent is specified, a default agent is used. It has the tools to manipulate sandboxes and other Crafting resources, and is able to transfer into a workspace if the prompt indicates work to be done inside a workspace.

Agent Skills Support

When running inside a workspace, the agent automatically discovers Agent Skills from the following locations:

/etc/sandbox.d/agents/skills: skills defined at the global level; can be baked into a base image or snapshot.
~/.agents/skills: skills defined for the current user. These override global skills with the same name. If .agents/skills does not exist, skills are looked up from popular clients, such as .github/skills or .claude/skills. Only the skills of a single discovered client are used.
<CHECKOUT-PATH>/.agents/skills: skills defined in the checked-out codebase. These override all of the above with the same name. Similarly, if .agents/skills does not exist, skills are looked up from popular clients, and the first discovered location is used.

If multiple checkouts are defined in the workspace, skills from the checkout defined first will override those from checkouts defined later.