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 0.4.2 or later. The SDKs 0.3.0 expect core 0.7.1, which adds sign-in by pairing, the tools list and the reasoning cap.
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. The limit covers MCP tools, knowledge search, attachment search and the system tools, and holds when a tool runs: a call to a tool outside it gets a tool error, "not available to this agent", even if the model names the tool on its own. Host tools are not affected. |
| 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.
An agent's version can also carry settings for the app's interface under ui. One is ui.reasoning.max, the highest level of thinking the agent allows, from none, minimal, low, medium, high, xhigh to max. The gateway lowers a request's reasoning_effort to it, or sets it when the request names none, and the SDKs offer the person only the levels up to it. A value that is not a level means no cap. Needs core 0.7.1. See the SDK pages: .NET, TypeScript.
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 proves who they are once, in one of two ways:
- By pairing (core 0.7.1 and later; the shape of RFC 8628, the OAuth device grant). The app asks the server for a pairing and shows the short code it gets. The person opens the console's
/pairpage, signs in however the server lets them (password, single sign-on, MFA), compares the code with the app's and approves or denies. The app then collects its tokens. It never sees a password, and a person whose login needs a second step can sign in. - With a login token: a password login or a single sign-on token, which the SDK exchanges at once.
- By pairing (core 0.7.1 and later; the shape of RFC 8628, the OAuth device grant). The app asks the server for a pairing and shows the short code it gets. The person opens the console's
- Either way the app ends up with 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.
One pairing for several agents. An app suite, such as the Office add-ins, names up to eight agents in one pairing. The console lists them all, the person approves once, and the app collects one sign-in per agent, each once. The approval covers only the agents the person may use. If the person may use none of them, the approval is refused, with the same answer whether an agent is unknown, retired or not granted.
The code the person compares is shown on the app's screen. The code the app polls with never appears on screen, in a log or in an address. The routes are in Agents. For the code, see the SDK pages: .NET, TypeScript.
The server's tools¶
An app can list the server's MCP tools that exist for its agent, for a "from your server" list: GET /v1/agents/{agent}/tools (core 0.7.1 and later). Each entry has the tool's name, its server's name, a short description, allowed (the agent's version lets the model be offered it) and enabled (an administrator has the tool and its server switched on). How a server is reached is never listed. The SDKs call it ListToolsAsync (.NET) and listTools (TypeScript).
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.