instance.record_tool_call

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_call(
    tool_name,
    tool_args=None,
    tool_call_id=None,
    conversation_id=None,
    user_id=None,
    customer_id=None,
    session_id=None,
    metadata=None,
)

await sdk.instance.record_tool_call(options: RecordToolCallOptions)

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

record_tool_call() tells Synap which tool your agent is invoking and with what arguments.

Prefer this over send_message(event_type="tool_call", ...). Each event carries both an event_type and a role, and the two have to agree; this method sets both. A tool call reported with the wrong role is read as an ordinary assistant reply, which is silent and changes what the anticipation agent believes happened.

Parameters

string

required

The tool being invoked.

dict

JSON-encodable arguments.

string

Your framework’s id for this call. Pass the same id to record_tool_result and the two are read as one exchange. Without it, a turn with three tools in flight is three calls and three results with nothing saying which belongs to which.

string

The conversation this call 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_call(
    "lookup_order",
    {"order_id": "A-1042"},
    tool_call_id="call_1",
    conversation_id=conversation_id,
    user_id="user_789",
    customer_id="cust_456",
)

await sdk.instance.record_tool_call({
  tool_name: 'lookup_order',
  tool_args: { order_id: 'A-1042' },
  tool_call_id: 'call_1',
  conversation_id: conversationId,
  user_id: 'user_789',
  customer_id: 'cust_456',
});

What happens to it

A tool call is a short-lived hint for the anticipation agent, like reasoning. It is not written to conversation history, not compacted, and not extracted into long-term memory. It is also mid-turn, so the agent observes it rather than pushing a bundle your agent would have already raced past.

Raises

error

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

Introduction

Lifecycle

Memory ingestion

Memory management

Conversation

Conversation context

Scoped context

User profile

Real-time streaming

Cache management

Credits & billing

Reference

Limits & Pricing

instance.record_tool_call

Parameters

Returns

Example

What happens to it

Raises

See also

​Parameters

​Returns

​Example

​What happens to it

​Raises

​See also

Parameters

Returns

Example

What happens to it

Raises

See also