Agent and terminal MCP tools

Agent and terminal tools create new Solo-managed processes and help MCP sessions identify the caller.

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.

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.

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.