instance.record_tool_result

Requires maximem-synap 0.5.1 or newer (Python) and @maximem/synap-js-sdk 0.5.1 or newer (JS). Earlier versions do not have this method, and 0.5.0 loses events sent immediately after listen().

await sdk.instance.record_tool_result(
    result,
    tool_name=None,
    tool_call_id=None,
    conversation_id=None,
    user_id=None,
    customer_id=None,
    session_id=None,
    metadata=None,
)

await sdk.instance.record_tool_result(options: RecordToolResultOptions)

Advanced: for real-time integrations. Requires an active instance.listen stream.

record_tool_result() reports what a tool handed back. The result travels in its own field rather than in content: it is not something a person said, and content is the field every reader treats as speech.

A tool result is usually your customer’s data. An order, an account, a record. It reaches us, it is used as an anticipation hint, and it is not written into long-term memory. Send what your agent needs in order to be understood, not the whole row. Whatever you do send is subject to your instance’s PII policy. The result’s words live only in the anticipation agent’s working thread: it keeps the 80 most recent events, expires 30 minutes after the last event, and is deleted when the session ends. Synap’s debugging records keep only the shape of the step, for 30 days, and not the result itself. See Traces and tool calls.

Parameters

any

required

JSON-encodable, or a plain string. A string is sent as itself, not as a quoted JSON string.

string

The tool that produced it.

string

The id you passed to record_tool_call. This is what ties the result to the call that asked for it.

string

The conversation this result belongs to.

string

External user identifier.

string

External customer identifier. Required on B2B. Not accepted on B2C.

string

External session identifier. Usually unnecessary.

dict[str, str]

Extra string key-value pairs.

Returns

Returns None.

Example

await sdk.instance.record_tool_result(
    {"status": "shipped", "eta": "2026-10-02"},
    tool_name="lookup_order",
    tool_call_id="call_1",
    conversation_id=conversation_id,
    user_id="user_789",
    customer_id="cust_456",
)

await sdk.instance.record_tool_result({
  result: { status: 'shipped', eta: '2026-10-02' },
  tool_name: 'lookup_order',
  tool_call_id: 'call_1',
  conversation_id: conversationId,
  user_id: 'user_789',
  customer_id: 'cust_456',
});

Raises

error

No stream has been started, or it has been stopped. A stream that is mid-reconnect does not raise.

SDK reference

Lifecycle

Write memory

Read context

Manage

CLI and errors

Resources

instance.record_tool_result

Parameters

Returns

Example

Raises

See also

​Parameters

​Returns

​Example

​Raises

​See also

Parameters

Returns

Example

Raises

See also