instance.listen() opens, so it needs a long-running process. The REST way to report a turn is conversation.record_message.
Advanced: for real-time integrations. Requires an active
instance.listen stream. If the stream is not active, this call raises ListeningNotActiveError.send_message() publishes a single agent activity event onto the bidirectional gRPC stream that listen() established. Each event tells the Synap platform what just happened in your agent (a user turn, an assistant reply, a tool call, or an explicit context request) so the platform can anticipate what context the agent will need next and push it back over the stream.
What the platform does with the event
Only
user_message and assistant_message become conversation history. Tool
calls, tool results and reasoning are short-lived hints for anticipation: never
compacted, never extracted into long-term memory. The anticipation agent reads
them in its working thread, which keeps the 80 most recent events, expires 30
minutes after the last event and is deleted when the session ends. The
debugging records keep only the shape of each step, for 30 days. See
Traces and tool calls.
Persisted turns feed both layers of context. They are the conversation that context compaction condenses as it grows, and Synap also turns them into long-term memory in the background.
Parameters
The message content. For
user_message and assistant_message events this is the natural-language turn; for tool_call events it can be a short description of the tool invocation.The conversation this event belongs to. Use the same id as for this conversation’s other calls. Neither SDK checks its format here.
External customer identifier. Required on B2B. Not accepted on B2C: passing it raises
CustomerIdNotAcceptedError before anything is sent. See B2C vs B2B.The kind of event being reported, from the table above. An unrecognised value is refused with an
InvalidInputError naming the real ones, rather than travelling to the server to be ignored there (Python 0.5.20 and JavaScript 0.5.18 and later).For
tool_call events: the name of the tool the agent is invoking. The platform uses this to classify the tool call and anticipate the agent’s next data needs.For
tool_call or context_request events: the retrieval queries the agent plans to run. Used as direct anticipation hints.For
tool_call or context_request events: the memory categories the agent plans to fetch.The model your agent runs on, for example
"gpt-4o", as on conversation.record_message. Synap uses its context window to decide when to compact this conversation. Overrides SDKConfig.agent_model for this event. Python 0.5.11 and later. JavaScript and TypeScript 0.5.9 and later.Your agent model’s context window, in tokens. Only needed for a model Synap does not know by name. It takes precedence over the model name. Overrides
SDKConfig.agent_context_window for this event. Python 0.5.11 and later. JavaScript and TypeScript 0.5.9 and later, as context_window (or contextWindow).The level of your scope ladder this conversation belongs to, for example
{"customer": "acme", "team": "payments", "user": "dana"}. Sent with the event; Synap keeps the first path it sees for a conversation and never overwrites it. Usually needed once per user: once a user has been placed at a level, customer_id and user_id alone reach their whole chain. Python 0.5.20 and later. JavaScript and TypeScript 0.5.18 and later, as scope_path (or scopePath).Returns
ReturnsNone. The coroutine resolves once the event has been written to the stream.
Example
A whole turn, in order
The five kinds of event a turn produces, with the typed methods where they exist. The typed methods setevent_type and role together, which is the
pair that has to agree.
No session call anywhere in that turn. The SDK opens one on the first event
and closes it when you stop listening. Call
end_session yourself only when a
conversation ends and your process keeps running.Raises
ListeningNotActiveError: wheninstance.listenhas not been called or the stream has been closed.InvalidInputError: an unknownevent_type, or nocontent(Python 0.5.20 and JavaScript 0.5.18 and later).CustomerIdNotAcceptedError, a subclass ofInvalidInputError: acustomer_idon a B2C instance (Python 0.5.12 and JavaScript 0.5.18 and later).
See also
- Real-Time Anticipation: how streaming and ingestion fit together.
- instance.listen: open the stream this method writes to.
- instance.stop_listening: close the stream.
- instance.record_thinking, record_tool_call, record_tool_result: typed methods that set the role for you.
- Event delivery: ids, acknowledgements, retries, and what to use without a stream.
- memories.create: the call that actually creates memories.