Agent and terminal MCP tools

Agent and terminal tools create new Solo-managed processes, help MCP sessions identify the caller, and manage the agent tools that agents launch from.

Tools#

• list_agent_tools — List enabled configured agent runtimes. Use each returned id as agent_tool_id for spawn_agent or spawn_process.
• spawn_agent — Preferred tool for creating a new Solo agent. Requires agent_tool_id from list_agent_tools; returns process_id, name, and optional agent_instructions.
• spawn_process — Generic create-and-start tool. Use kind: "terminal" for an interactive shell or kind: "agent" with an agent_tool_id; prefer spawn_agent for agent-only calls.
• identify_session — Identify this MCP session to Solo. With no arguments, auto-detect and report the current identity.
• whoami — Show how Solo identified this caller's process, actor, and effective project scope.

Spawning agents#

Both spawn tools accept these agent options:

• agent_tool_installation_id — The environment-specific installation of the agent tool to launch. Preferred over agent_tool_id alone when project-scoped agent discovery returns installations.
• name — Custom name for the spawned process; omitted names are auto-generated.
• extra_args — Per-launch arguments appended to the resolved agent command without changing the saved agent tool defaults.
• include_agent_instructions — Include bootstrap instructions in the response. Defaults to true.

If you pass both agent_tool_id and agent_tool_installation_id, they must refer to the same agent tool; otherwise the call is rejected.

By default, spawning an agent includes agent_instructions: a Solo orchestration preamble with the new process ID, project, and MCP tool hints. Set include_agent_instructions: false to omit them. When included, prepend them to the agent's first prompt, then send that prompt with send_input(process_id=..., input=...).

Spawning never changes the caller's own identity. Pass project_id to spawn into a different project without changing the session's default scope.

Managing agent tools#

These tools manage the global agent tool configurations shown in Settings > Agents > Agent tools:

• list_agent_tool_configs — List full agent tool configurations. Disabled tools are included unless you pass includeDisabled: false. Unlike list_agent_tools, which returns only enabled runtimes for spawning, this returns every editable field.
• get_agent_tool — Read one configuration by id.
• create_agent_tool — Add an agent tool from a required name and command. Optional fields are defaultArgs (default empty), icon (default terminal), toolTypeMode (auto, the default, detects the agent type; manual requires manualToolType), headlessCmd, promptMode (stdin, the default, or arg), and enabled (default true).
• update_agent_tool — Patch fields with {"id": 42, "patch": {...}}. Omitted fields are preserved, and headlessCmd: null clears the headless command. Changing the command or type clears the saved resume IDs of agents that use it.
• delete_agent_tool — Delete a configuration by id. It's idempotent, detaches processes that used it, and leaves those processes running.
• set_agent_tool_enabled — Enable or disable an agent tool by id. This affects future launches only; running agents keep going.
• list_agent_tool_installations — List detected installations of each agent tool with their cached health.
• refresh_agent_tool_installation_health — Re-check installations and refresh their health, like Refresh health in Settings.

The same operations are available through the HTTP API and the solo agents CLI commands.

Session identity#

Solo-managed agents are normally identified automatically. Use whoami to check the current identity, and call identify_session only if whoami cannot identify the session. identify_session has three modes:

• Auto-detect — Call with no arguments to detect and report the current identity. An optional pid (the caller's host OS PID) helps detection when nothing else matches.
• Self-assertion — Pass solo_process_id with this client's own value from the SOLO_PROCESS_ID environment variable, only when auto-identification failed. This is a Solo-managed process ID, not a host OS PID.
• External registration — Pass external with a display name (plus optional agent_id and metadata) when the caller runs outside Solo but needs an actor identity for coordination features like locks, todos, and scratchpads.

Never use identify_session to target another process. Use project_id parameters for project scope and delivery_process_id for timer delivery.

Notes#

Use spawn_agent or spawn_process for new work. Use start_process or restart_process from Process tools for existing Solo process entries, and close_process to remove stored terminals and agents.

Identification lets Solo associate timers, locks, todos, scratchpad activity, and process cleanup with the correct Solo process. Use whoami to confirm what Solo already knows about the session.