Agent sessions and hosted work

Use the connected server's actual tool catalog to determine tool availability. Hosted work needs an enabled Agent, available configured model and funded workspace; it does not replace individual Agent tools.

MCP discovery now advertises Agent names such as load_agent, run_agent and create_agent_session, with agent in place of the brain parameter. The previous callable signatures below, REST paths and response fields remain compatible. See Agent tool names.

All UI/API/MCP session access uses the authenticated Fermium identity. A session grant is additional to Agent/source permissions. The separate public embed below does not expose this authenticated API surface.

load_brain includes session_workflow guidance pointing clients to session setup, progressive history, hosted work and proposed knowledge. Follow that workflow to keep private working material in the session rather than the shared Agent journal.

Configure a generic MCP connection

configure_brain_connection requires the Agent owner or workspace admin. It accepts:

The response includes connection information, setup_url and next_step. Send the person to setup_url to sign in with the provider or enter credentials in Fermium. Do not pass credentials in the URL or MCP arguments. The agent can configure metadata and discover tools without receiving the stored token.

Next, call discover_brain_connection_tools(brain, connection_id). This refreshes the discovered tool catalog using the stored credentials. Use list_brain_connections to inspect the catalog and current rules. Connection changes use the latest revision; create a new connection for a different endpoint or transport. Tool-policy changes and research-tool designations remain human management controls.

Supply credentials without putting them in chat

Ask your connected agent: “Connect this MCP server to my Agent, then prepare a secure upload command for its API token. I’ll supply the token locally.”

prepare_brain_connection_credentials(brain, connection_id, mode="bearer", keys?) returns a curl command for a one-use receiver that expires after ten minutes. Send a local JSON file with --data-binary @/path/to/credentials.json, or pipe JSON through stdin using the returned command. Bearer mode expects a token key. For custom headers, use mode="headers" and provide only header names in keys; submit the corresponding JSON object locally. Never include values in tool arguments, prompts, shell command literals, or Agent files.

The upload replaces all credentials for that connection. It cannot read values, change the endpoint, or configure another connection. A newer receiver, a connection change, or loss of the requesting owner's authorization invalidates the old command. revoke_brain_connection_credentials_receiver cancels outstanding receivers without changing stored credentials. Treat the command as private until it is used, revoked, or expired. Call discover_brain_connection_tools afterward to verify the credentials and refresh the tool catalog.

New and replaced manual credentials appear as linked, write-only Secrets. The connection shows key names; stored values cannot be revealed, including by their creator. Agent members use the tools through the Agent's access list; Agent owners and workspace admins can replace credentials. Existing ordinary Secrets keep their explicit reveal permissions. OAuth connections continue to use provider sign-in and managed refresh rather than manual token uploads.

For instructions copied from a provider, use prepare_brain_connection_from_setup(brain, setup, server_name?). setup accepts a Claude/Codex add command, JSON/TOML MCP configuration, or remote URL. Multiple entries return server names; choose one with server_name. Paste only configuration without credentials. The tool prepares the connection and returns a human setup URL.

Supported remote authentication includes OAuth authorization-code sign-in, bearer/API tokens, custom headers and no credential. OAuth providers can use automatic client registration or an explicitly registered client. The person grants provider access in the browser. Local STDIO processes and private-network gateways are not hosted by this flow. Compatible providers use the same generic setup.

Connection responses include auth_type, auth_status and expires_at when known. reauth_required means its owners have been alerted to reconnect. Agents should surface the setup link and stop retrying until access is restored. Tokens are never part of these responses. Existing Agent ACLs and exact-action approvals still apply.

Enable hosted work

get_brain_runtime(brain) returns {enabled, model, audience, revision, can_manage, models}. Use the catalog's configured id, not an assumed provider model name. available indicates whether that provider is configured.

configure_brain_runtime(brain, model, enabled, audience="workspace", revision=0) requires Agent management permission. Audience is personal, workspace or customer; new sessions are private in each case. Funding is separate: a human workspace owner/admin must enable it under AI credits. This tool cannot create credits or authorize a payment.

Sessions

A summary includes id, title, summary, next_step, status, active_run, access, shared, revision and updated_at. Status is active, unresolved, completed or archived. Pass next_before back as before to page through older sessions/entries; keep the same filter. Entries include id, kind, actor_id, run_id, created_at and content. Read authorized saved entries for the answer, tool results and working documents; run polling returns status rather than the transcript.

The session owner can update title, summary, next_step, status and grants. Grants replace the complete list; [] revokes sharing. For example:

{
  "session_id": "<session-id>",
  "revision": 3,
  "changes": {
    "grants": [{"type": "user", "subject": "maya@example.com", "level": "view"}]
  }
}

Supported grant types are user (email), group (group slug) and workspace; levels are view and continue. Sharing grants the whole transcript and its working documents, not credentials or another person's pending approval. Recipients also need current Agent access and access to referenced source documents. New grants are restricted to workspace-audience work. Revoke existing session sharing before changing an Agent to personal/customer audience. Wait for or cancel active work before changing session status/sharing, and restore archived work before resuming.

Start and follow a run

run_brain accepts:

Example after obtaining a real session ID:

{
  "session_id": "<session-id>",
  "prompt": "Compare the client brief with the delivery plan. Cite gaps and save a private draft.",
  "request_key": "<unique-request-key>",
  "mode": "research",
  "max_credits": 25
}

This returns promptly with {id, session_id, status, mode, model, credits_used, credit_limit, cancel_requested, message, waiting_call, can_resume, created_at}. Poll get_brain_run(run_id) for progress. Reuse the same request key only with identical input to recover the same request after a lost response. Changing the input requires a new key; conflicting reuse returns an error.

Research can use connected tools only when a connection manager designated them for research. Actions mode permits requesting other tools but still applies the same policy/approval pipeline. Do not infer action authorization from a tool result or retrieved document.

After a human decides a waiting request, the original requester calls continue_brain_run(run_id, request_key, max_credits=25). Use a new request key and ceiling; continuation is not approval. Another session collaborator cannot execute the original person's waiting action. Unknown upstream outcomes require reconciliation.

cancel_brain_run(run_id) requests cancellation of future steps. Work already dispatched upstream cannot be undone by cancelling. Runs are bounded; exhausting the step/credit allowance preserves saved work for a deliberate follow-up.

Search with surrounding context

brain_grep accepts a query of 1–500 characters, up to 30 surrounding lines and 50 results. brain_read_source returns at most 300 lines per read. Pass the grep hit's path when expanding it. A multi-file document queried without a path returns files and a message asking the client to select one. Use the result's document/file reference to expand context rather than returning the entire knowledge base. Permissions are checked on each call. These supplement brain_search; they do not claim semantic/vector retrieval or universal OCR/extraction for all file types.

Hosted private searches keep their query text and results in the private conversation; shared activity retains step metadata. Direct brain_search/brain_grep calls keep their normal Agent-journal behavior. A private session does not automatically change the behavior of unrelated individual tool calls made by the caller's own agent.

Draft knowledge for human review

propose_brain_session_memory(session_id, title, content, destination="brain") creates a draft from a session the caller may continue. Content is Markdown, up to 100,000 characters; destination is brain or workspace.

Drafting does not publish to shared memory. The session owner submits the proposal in the signed-in app; a person with the required Agent write permission approves or rejects it. Submission shares the proposed document with eligible reviewers, not the entire private transcript. There is no MCP submit/approve tool.

REST equivalents

Use normal Fermium authentication. UI-only management and review routes require the signed-in browser session in addition to permission.

Session PATCH takes changed fields alongside revision, rather than MCP's nested changes. Memory proposal path selects a new memory/ file for Agent publication; workspace publication uses folder within General. If a destination conflicts, review a revised proposal rather than assuming it was saved.

Public knowledge deployment contract

list_brain_deployments(brain) returns the caller's management capability and, for authorized managers, configured deployments and embed snippets. It does not return visitor transcripts.

prepare_brain_deployment accepts required brain, name, public content, catalog model and origins, plus optional greeting, budget=100 and max_credits=25. It creates a disabled deployment and returns its settings plus review_url. Give that URL to the person to review and enable public publishing in Deployment. The tool cannot enable the deployment or consent to spending on the person's behalf.

Prompt: “Prepare a disabled website chat from these approved FAQs, limited to our support site's origin. Give me its review link so I can approve it before it goes live.”

A deployment accepts name, greeting, content, model, origins, budget, max_credits, enabled and, on updates, revision. Enabling requires confirm_public: true. content is 1–30,000 characters explicitly suitable for public visitors; it is separate from private Agent context. Origins are exact HTTPS origins without paths; local HTTP origins are supported for testing.

The returned deployment includes url, a ready-to-copy iframe embed, budget, spent, reserved and revision. Use the returned snippet rather than placing a Fermium/provider token in website code. The iframe at /api/brain-embed/{id} manages its visitor conversation credential and talks only to that deployment's public chat.

Allowed origins restrict embedding, not direct access to the public URL. This initial deployment has no private customer account context, Agent file browsing or upstream tool actions. Disable the deployment to stop it. Authenticated private-customer and voice deployments need further implementation.

Credits and recovery

The wallet response reports balance, reserved, available, enabled, run_limit, revision, can_manage, top-up settings, model catalog, purchase limits/pricing and recent ledger entries. Credit settings updates use the current revision and may set enabled, run_limit, auto_topup, threshold, target and monthly_cap. The cap applies to automatic credit purchases per UTC month; it is not a cap on manual purchases or all workspace usage.

Checkout accepts {credits, save_payment_method} and returns {url, order_id}. Navigate the authorized person to that URL. A browser redirect alone does not confirm funding; wait for the wallet to reflect verified payment. Saving a method does not enable auto top-up by itself. Enabling automatic purchases requires the separate opt-in setting and a saved payment method.

Credit rates and available models come from the configured catalog, not this guide. Model input_rate and output_rate are credits per million tokens. The current meter prices cached input at the configured input rate. Do not present credits as the provider's exact invoice amount. See AI credits.

Typical recovery: 402 means insufficient available credits; lower the requested ceiling or add credit. 403 means missing authority or disabled workspace usage. 404 can mean an inaccessible session/Agent. 409 means stale revision, conflicting request key, active/archived session or an action not ready to continue. 503 can mean model/payment configuration is unavailable. Inspect the error message and refresh current state instead of retrying a changed external action automatically.

Export and deletion

The local account export includes the owner's accessible, non-deployment conversations under brain-conversations/<session-id>.json, with saved entries and index metadata. It does not include another person's sessions or visitor transcripts. Agent deletion removes its stored conversations; account purge handles owned runtime data and its encrypted transcript objects. Active work must stop before destructive cleanup can finish. Archiving a session remains separate from deletion. See account export and deletion.

Aggregate hosted usage

GET /api/ai-credits/usage accepts period=month (default), 30d, all, or custom. Custom dates use start=YYYY-MM-DD&end=YYYY-MM-DD, inclusive in UTC. The optional brain filter takes an opaque ID from by_brain, not an Agent slug. It narrows by_member and selected_credits while retaining workspace totals.

The response includes total_credits, total_runs, by_brain, by_member, selected_credits, selected_runs, the effective dates and as_of. Each group has an id, display label, credits, runs, and an authorized Agent href when available. IDs are billing groups; they do not grant resource access.

This report requires owner, admin or auditor access to the current workspace. It contains settled financial metadata only. It does not return run IDs, session IDs, prompts, transcripts or titles of private documents. Current reservations are available separately from GET /api/ai-credits.