Agents and adapters
The adapter decides what an agent actually is. The NuFi one runs on the gateway with no sandbox; the coding ones need a sandbox most instances do not have.
An agent in Works is an employee: a name, a role, a place in the org, and an adapter. The adapter is the consequential part. It decides what the agent actually is when it runs.
Choosing an adapter
| Adapter | Use for | Runs |
|---|---|---|
nufi_agent | Knowledge work: research, drafting, review, answering from company documents | A NuFi model through the gateway, in the server's own process |
claude_local, codex_local, opencode_local, pi_local | Repository work: code, pull requests | A coding harness in a sandbox with a git workspace |
The coding adapters need a sandbox, and most instances do not have one. They also need that vendor's own API key. If your instance has no sandbox provider configured, an agent on one of these adapters cannot run at all.
nufi_agent has no such dependency: it calls the gateway directly and
needs no sandbox. For knowledge work it is both the working choice and
the cheaper one.
The setup wizard and the New Agent dialog both recommend NuFi Agent and keep the coding adapters behind More Agent Adapter Types, which matches what an instance can actually run.
Adding an agent
See all agents in the rail opens the Agents page; New Agent is top-right.
Give it a name and a role, and choose its adapter and model — the same choice as the wizard's step four. The page's tabs (All, Active, Paused, Error) are the quickest read on which agents will actually act on a task: a paused agent holds work without running it. The icon beside the tabs switches between the list and the org chart.
The NuFi adapter
nufi_agent reaches models two ways:
| Target | What it does |
|---|---|
gateway (default) | Calls a model through the NuFi gateway |
chat | Uses an agent you already built in the NuFi chat app, with its tools, MCP and documents |
The second is worth knowing about: if a colleague has already built a good assistant in chat, an agent in Works can be that assistant rather than a reimplementation of it.
Credentials
The adapter's configuration names the environment variable holding the model key, never the key itself — adapter config is visible in the interface.
The normal arrangement is per person: bind NUFI_MODEL_API_KEY on the
agent as a user secret, and each member connects their own NuFi account.
Runs then bill whoever the work belongs to, and revoking one person's
access does not disturb anyone else.
See Connecting your NuFi account.
An agent with no binding falls back to a server-wide key if the operator configured one — which is the shared-credential arrangement the per-user setup exists to replace. Worth checking rather than assuming.
Enabled, paused, running
The dashboard counts agents as enabled, and breaks that into running, paused and errored. A new company's two built-in agents arrive paused: they exist, they are configured, and they will not do anything until someone starts them.