start_session
Generate a fresh session_key for multi-turn conversation with a fleet
agent. Pass the returned key as session_key to subsequent invoke_agent
calls to preserve context. Conversation state is persisted server-side by the
agent gateway under this key — the bridge itself stores nothing.
Arguments
| Argument | Type | Required | Notes |
|---|---|---|---|
agent | string | no | Agent name to validate. The returned key works for any agent, but pre-validation surfaces typos early. |
Return value
A text content block containing JSON with a session_key field — a fresh
UUID string.
Example call
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"start_session","arguments":{"name":"researcher"}}}
Example result:
{"session_key":"00000000-0000-4000-8000-000000000000"}
Then use it in invoke_agent as the session_key argument. The key is
opaque: it is sent to the gateway as the x-openclaw-session-key header and
is not bound to the agent it was generated against.
Failure modes
unknown agent: {name}— the optionalagentargument names an agent not inagents.json. This is the only waystart_sessionfails; omittingagentalways succeeds.- Session keys are generated client-side by the bridge (
randomUUID), so key generation never touches the network and cannot fail on gateway problems. A key for a downed agent simply fails later ininvoke_agent.
Notes
invoke_hermesdoes not accept session keys — Hermes one-shot mode does not preserve context across calls.- To reset context, call
start_sessionagain and switch to the new key.