Start an agent session
create_agent_sessionStart an agent session and queue a first prompt, receiving replies asynchronously through session history. Target either your own session or an incident's shared session.
Instructions
Start a session with an agent and send it a first prompt. The agent replies asynchronously: this returns once the prompt is queued, and the reply is read from GET /sessions/{session_id}/history/messages. incidentId names the incident the session is about. With sessionMode USER, the default, the session is the caller's own, so it needs an OAuth token or a user API key, and a workspace API key gets 400. With INCIDENT it is the incident's, visible across the workspace, and an incident's open session takes the prompt instead of a new one starting. With hidden true the prompt still runs the turn, but its prompt.accepted history event is marked hidden so a client can leave it out of the conversation. Needs a grant to run the agent, and to view the incident when incidentId is set.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"agentId": "<agentId>",
"prompt": "<prompt>"
},
"name": "create_agent_session"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| effort | No | ||
| hidden | No | ||
| prompt | Yes | ||
| agentId | Yes | ||
| modelId | No | ||
| incidentId | No | ||
| sessionMode | No | USER | |
| pipelineEditorContext | No | ||
| X-Orchestra-Account-Id | No | Act on this account rather than the one the credential resolves to. Omit it to use the credential's own account. An API key is issued to a single account, so it may only name that account; an OAuth token may name any account its grant covers. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||