Agents¶
The routes an agent's app uses. The SDKs call them for you; this page is for reading traces, or for writing a client in another language.
Server version
These routes come with the next Fadenstack release, after 0.4.1.
Signing in¶
| Route | Does |
|---|---|
POST /api/auth/jwt/login |
The user's login, with a form body username (email) and password. Returns a login token. Single sign-on gives the same token. |
POST /api/agent-tokens |
Exchanges the login token for an agent sign-in on this device. Body: {"agent": "<address>", "device_label": "My laptop"}. Returns an access token, a refresh token and their lifetimes, and the device id. |
GET /api/agent-tokens/mine |
The user's agent sign-ins, per device |
DELETE /api/agent-tokens/{device_id} |
Ends a sign-in |
Renewing with a refresh token returns a new refresh token; the old one stops working. Using an old one again ends the sign-in on every device, with refresh_token_reused. These routes report errors as {"detail": {"code": ..., "message": ...}}.
Working as an agent¶
All take the agent's access token as Authorization: Bearer.
| Route | Does |
|---|---|
GET /v1/agents/{agent}/profile |
The agent's profile. See Agents on the server. |
PUT /v1/agents/{agent}/manifest |
Reports the app: its name and version, the SDK, its tools (name, description, parameters as JSON Schema, class) and its greeting. Returns whether the server has seen this report before. |
POST /v1/agents/{agent}/chat/completions |
Chat, as on /v1/chat/completions. The agent's model is used, whatever model says. |
POST /v1/agents/{agent}/approvals/{id} |
Answers an approval the server asked for |
POST /v1/agents/{agent}/events |
Reports what the agent did: up to 100 events per call |
Headers on agent chat¶
| Header | Means |
|---|---|
X-Faden-Tool-Mode |
The session's tool mode: off, read_only, ask or auto |
X-Faden-Conversation-Id, X-Faden-Turn-Id |
Ties requests to a conversation and a turn on the device (1 to 128 characters of letters, digits and ., _, :, -) |
X-Faden-PII-Mode |
redact or tokenize_reversible, if the agent lets the user choose |
X-Faden-Events: ag-ui |
Switches on the extra events |
When the agent's tool contract is not empty, tools the app offered that the contract does not list are held back until an administrator accepts them, and the response's X-Faden-Held-Tools header lists them. Nothing is held back while local MCP servers are allowed on the device.
Limits¶
A manifest is at most 512 kB, with up to 200 tools and up to 100 context entries. A tool's description is at most 4,000 characters and its parameters at most 32 kB.