Agents on the server¶
What the server keeps about an agent, and how an app signs in to it.
Server version
Agents need a Fadenstack server from the next release, after 0.4.1.
An agent and its versions¶
An agent has an address (its slug, for example my-assistant), a name, and a list of versions. A published version never changes: to change an agent, an administrator publishes a new version, and can roll back to an earlier one. An agent can also be retired, restored and deleted.
A version holds:
| Field | What it decides |
|---|---|
| Instructions | How the agent behaves. They stay on the server; clients get only a fingerprint of them. |
| Model | Which model answers. On agent requests the agent's model always wins over what the client asks for. |
| Knowledge | Which document collections the agent may search. |
| Server tools | Which tools on the server the agent may use: none, all a chat could use, or a list. |
| Host tool contract | Which tools the app may offer, each with a class and an approval rule. See below. |
| Local MCP | Whether the app may start local MCP servers. |
| Greeting and suggestions | What an empty chat shows. |
The profile a client gets¶
When an app starts, the SDK fetches the agent's profile: its name, version, model, the host tool contract, the server tools, the local MCP setting, the tool modes the user may pick, the privacy settings, the greeting and suggestions, and any client modules the agent requires. The SDK applies it; you rarely read it yourself.
The host tool contract¶
The contract lists the host tools the agent may offer, each with:
- a class: read, write or destructive. It can make your tool's class stricter, never looser.
- an approval rule: never ask, ask in the user's mode, or always ask.
- a fingerprint of the tool's parameters, so a changed tool counts as changed.
Apps and their tools¶
An app reports itself when it connects: its name and version, the SDK, and the tools it offers with their descriptions, parameters and classes. The server keeps each distinct report.
When the agent's tool contract is not empty, a tool the published version does not list is held back: the model does not see it. On the agent's Apps tab an administrator sees each tool marked as new, changed, riskier or unused, and publishes the reviewed set with Accept and publish.
Who may use it¶
An administrator grants an agent to people or teams. Access is checked when a user signs in and every time the sign-in is renewed, so removing someone takes effect within minutes.
Sign-in on a device¶
- The user logs in to Fadenstack once, with a password or single sign-on.
- The SDK exchanges that login for an agent sign-in for this agent on this device, with a device label the user can recognise later.
- The sign-in consists of a short-lived access token and a refresh token. The SDK renews the access token by itself; each renewal replaces the refresh token. If an old refresh token is ever used again, the server ends that sign-in everywhere.
- An unused sign-in expires after some days of inactivity, and every sign-in after some weeks; the server's settings decide how long.
Users can see and end their sign-ins per device, and administrators can sign out a device for them.
Events¶
The SDK reports what the agent did: which tools ran and how long they took, approval decisions, local MCP servers it attached, and session statistics. These events carry no message content. They show up next to the chat's usage in the console.