Agents and Assistants
Connect local or SSH agents, create reusable assistant roles, and distinguish them from models and Bots.
Open: Settings → Agents or Assistants.
Configure an agent to change how tasks run. Create an assistant to give recurring work consistent instructions. Start with the built-in Nexts AI agent if you do not need an external executor.
Understand the four concepts
| Name | Responsibility | Example |
|---|---|---|
| Model | Understanding and generation | Choose a model that accepts images |
| Agent | Execution, model connection, and tools | Nexts AI or an external CLI connected through ACP |
| Assistant | Reusable instructions and default capabilities | Review documents against a fixed checklist |
| Bot | A persistent assistant space | Maintain separate material, memory, and routines |
External agents use their own supported authentication, models, and tools. Configuring a Nexts model does not sign an external CLI in. See Bots for persistent workspaces.
Use a local agent
- Open Agents → Local, find the agent, and inspect its installation and connection status.
- If needed, open its menu and use Install CLI or Install adapter when available. Check the target host and command in the confirmation. Follow the instructions for manually installed entries.
- Complete authentication or model configuration in that CLI, then return to Nexts.
- Select Test connection. Resolve authentication or connection errors shown in the details and retry.
- Select the agent and start a new conversation with a small read-only task, such as listing the project's top-level files and explaining their purpose.
Success: the selected agent returns a result in chat. A connection test checks the protocol handshake without creating a session or calling a model. A real conversation verifies authentication and model availability.
Add a custom or SSH agent
A custom configuration needs a unique ID, name, executable, arguments, and any required environment variables. Arguments are a JSON array of strings; environment variables are a JSON object of string values. Save and test the connection.
For SSH, first connect from a terminal using system OpenSSH and key authentication, and verify the host fingerprint. Enter the host, port, user, and an existing absolute remote working directory. Specify a private key path if required. Detection, installation, and agent execution then target that host.
Commands and paths belong to the remote host. This is separate from remote access, which lets a phone access your desktop Nexts.
Advanced JSON edits the full configuration and validates it before saving. Environment variables may contain credentials; do not share the whole file. Deleting a configuration removes the connection definition without uninstalling the CLI or deleting conversations.
Create a document review assistant
-
Open Settings → Assistants, create a custom assistant, and enter a name and purpose.
-
Describe its input, review scope, and output format:
Review product documentation. Check that entry points, prerequisites, steps, and success criteria are clear. Report the location, problem, and suggested correction. Mark unverified features. -
Choose its agent, default tools, skills, memory scope, and approval mode as needed.
-
Save, select the assistant in chat, and test it on a short document.
-
Review the output, adjust its instructions, and verify them with a new task.
Copy a built-in assistant into a custom one to change read-only details. Role instructions do not install tools, authorize accounts, or activate a model service.
Collaborate with several assistants
In a custom assistant, choose the built-in Nexts AI backend and enable Multi-member collaboration. Select existing assistants or agents and assign responsibilities. Up to 12 members are supported, without nested groups. Address a member with @member, or let the current assistant coordinate assignments.
Test a small sequence such as research, review, and synthesis. Members retain task context within the current conversation, with separate contexts across conversations. This does not merge independent Bot memories.
Troubleshoot
| Symptom | Next step |
|---|---|
| Installed CLI cannot connect | Check authentication, executable, arguments, and adapter; test again |
| Handshake works but chat fails | Check the agent's own model, account, and quota |
| An expected tool is missing | Check assistant defaults, agent support, and the tool connection |
| Built-in role cannot be edited | Copy it into a custom assistant |
| Approvals behave differently | Review the current agent and chat permission mode |