Skip to main content
    Ivy Biosciences Docs/Call the platform/API/Sessions API/Message execution

    Message execution

    Execute messages with SSE streaming, the StreamEvent reference, interrupts, sub-agents, and human-in-the-loop

    sessionsstreamingssetools

    This endpoint is deprecated and answers 410 Gone.

    This endpoint runs a single turn in a session and streams everything that happens back to you as it happens — the model's text as it's generated, each tool call, job progress, sub-agent activity, and pauses for approval. Reach for it once you've created a session in Manage sessions and want to send a message and watch the response unfold live. Every turn ends with a sync event so your client knows the stream is complete.

    Difficulty

    advanced

    Time

    20 min

    Message Execution

    Request

    contentstringrequired

    The user message to execute

    streambooleandefault: true

    Set to false for non-streaming mode (returns final state as JSON)

    clientIdstring

    Client identifier for version vector tracking. Auto-generated as api_{Date.now()} if not provided.

    Example Request

    curl -N -X POST "https://yourapp.com/api/v1/sessions/$SESSION_ID/execute" \
      -H "Authorization: Bearer ivy_your_key" \
      -H "Content-Type: application/json" \
      -d '{"content": "Run ADMET prediction on aspirin"}'

    SSE Response Format

    The response has Content-Type: text/event-stream. Each event is one data: line holding a flat JSON object; its type field names the event and the other fields sit beside it, not under a data key:

    data: {"type":"turn.started","turnId":"..."}
    
    data: {"type":"message.delta","delta":"I'll run an ADMET prediction..."}
    
    data: {"type":"tool.started","toolCall":{"id":"tc_001","name":"admet_ai","arguments":{"smiles":"CC(=O)Oc1ccccc1C(=O)O"}}}
    
    data: {"type":"sync.completed","sessionId":"..."}

    After the runtime finishes, the route writes a final sync.completed event and closes the stream. If the runtime throws mid-stream, the route writes an error event with code: "EXECUTION_ERROR" instead and closes.


    StreamEvent Types

    The event union is StreamEvent in @pleach/core; that type is the authority, and new event types are additive. Handle the ones you need and ignore the rest. Every event may also carry namespace (a sub-agent path; empty for the root agent).

    Message Events

    EventFieldsMeaning
    message.addedmessageA message was appended to the session
    message.deltadelta, callClass?A chunk of answer text
    reasoning.deltadeltaA chunk of model reasoning, never answer text
    message.completemessage, usage?, finishReason?Ivy's message is final
    message.citationscitations, sectionCitations extracted for the message
    message.entitiestoolCallId, toolName, entitiesLinkable entities (genes, compounds, …) found in a tool result
    thinking.delta / thinking.completedelta / thinkingExtended-thinking text
    content.resetreason, failedModel?Discard the text streamed so far; a retry follows
    content.correctioncorrectedContent, reasonReplace the streamed answer with this text
    content.preview / content.suppressedreason, …Interim text the runtime withheld or marked provisional

    Tool Events

    EventFieldsMeaning
    tool.startedtoolCallThe model called a tool
    tool.deltatoolCallId, deltaStreaming tool output
    tool.completedtoolCall, resultThe tool returned
    tool.failedtoolCall, errorThe tool failed
    result.offloadedtoolName, filename, sandboxPath, sizeBytes, rowCount?A tool result was written to the sandbox instead of the prompt

    Job Events

    EventFieldsMeaning
    job.dispatchedjobA compute job was submitted
    job.progressjobId, progress, phase?, statusMessage?, estimatedRemainingMs?Progress from the backend
    job.completedjobThe job finished
    job.failedjobId, errorThe job failed
    jobs.pendingjobsJobs still running when the turn ended

    Artifact, Checkpoint and Sandbox Events

    EventFieldsMeaning
    artifact.createdartifactA new artifact reference
    checkpoint.createdcheckpointA checkpoint was saved (see Checkpoints)
    sandbox.createdsandboxId, tunnelUrlThe chat's sandbox started
    sandbox.terminatedsandboxId, exportedFilesThe sandbox stopped

    Interrupt Events

    EventFieldsMeaning
    interrupt.requestedinterruptA tool call is waiting for approval
    interrupt.resolvedinterruptId, decisionThe approval was answered

    Sub-Agent Events

    EventFieldsMeaning
    subagent.spawnedsubagentId, task, specName?A sub-agent started
    subagent.progresssubagentId, progress, message?, activeToolName?Sub-agent progress
    subagent.completedsubagentId, content, toolsUsedThe sub-agent returned
    subagent.failedsubagentId, error, terminalStatus?The sub-agent failed, timed out or was cancelled

    Session and Sync Events

    EventFieldsMeaning
    session.created / session.resumed / session.updatedsessionThe full SessionState
    sync.started / sync.completedsessionIdSync boundaries; the route's last event is sync.completed
    sync.conflictsessionId, resolutionA conflict was resolved as local, remote or merged
    context.summarizedoriginalMessageCount, compressedTokensOlder history was condensed

    Turn and Error Events

    EventFieldsMeaning
    turn.startedturnId?The turn began
    turn.completedoutcome, durationMs, abortedByUser?The turn ended as ok, error or interrupted
    turn.metricscontext, toolsContext-window use and tool counts for the turn
    errorerror, code?, httpStatus?A runtime error
    stream.truncatedreason, partialLengthOutput was cut off by a repetition guard
    stream.reconnecting / stream.disconnectedattempt, maxRetriesProvider stream retries

    Diagnostic Events

    The runtime also emits diagnostic events. Clients that render a conversation can ignore any event type they do not handle.


    Non-Streaming Mode

    Set stream: false to receive the final state as a single JSON response instead of SSE:

    curl -X POST "https://yourapp.com/api/v1/sessions/$SESSION_ID/execute" \
      -H "Authorization: Bearer ivy_your_key" \
      -H "Content-Type: application/json" \
      -d '{"content": "What tools are available?", "stream": false}'

    Returns {"success": true, "events": [...], "state": {...}}: every event the turn produced, and the last SessionState seen in a session.updated or session.resumed event (or null if none was emitted).


    Interrupt Flow (Human-in-the-Loop)

    The runtime's InterruptConfig names the tools that pause for approval (interruptBefore, interruptAfter). The REST create route does not take it: POST /api/v1/sessions reads only config.provider, config.model and config.tools, so which tools pause is set by the host application.

    When a turn reaches a gated tool:

    1. The stream emits interrupt.requested with the pending interrupt.
    2. Your client answers with POST /api/v1/sessions/:sessionId/interrupt/:interruptId/resolve and a body of {"approved": true} or {"approved": false, "note": "..."}.
    3. The stream emits interrupt.resolved and the turn continues.

    The SSE connection stays open while the interrupt waits. Set client-side timeouts that allow for a person to answer.


    Was this page helpful?

    On this page

    On this page

    Loading...