Python SDK: Sessions

Run agents and follow their events. The SDK adds the agents beta flag for you.

from syntic import Syntic
 
client = Syntic()  # reads SYNTIC_API_KEY

Methods

sessions.create

Start a session, optionally with first events. Maps to POST /v1/sessions.

result = client.sessions.create(
    agent_id="agt_01JC4R8W6Q2N9X3T5V7Y",
    input=[{"type": "user.message", "content": "Where is my refund?"}],
)

sessions.send

Send user messages, tool results or approvals. Maps to POST /v1/sessions/{session_id}/events.

result = client.sessions.send(
    'sesn_01JC7M2K4P6R8T0V2X4Z',
    events=[{"type": "user.message", "content": "Thanks!"}],
)

sessions.stream

Iterate live events; reconnects with Last-Event-ID automatically. Maps to GET /v1/sessions/{session_id}/stream.

with client.sessions.stream('sesn_01JC7M2K4P6R8T0V2X4Z') as stream:
    for event in stream:
        print(event)

sessions.events.list

Full history, paginated. Maps to GET /v1/sessions/{session_id}/events.

for item in client.sessions.events.list('sesn_01JC7M2K4P6R8T0V2X4Z', limit=100):
    print(item.id if hasattr(item, 'id') else item)

sessions.interrupt

Stop the current turn. Maps to POST /v1/sessions/{session_id}/interrupt.

result = client.sessions.interrupt('sesn_01JC7M2K4P6R8T0V2X4Z')

sessions.resources.add

Mount a file, repository or memory store. Maps to POST /v1/sessions/{session_id}/resources.

result = client.sessions.resources.add(
    'sesn_01JC7M2K4P6R8T0V2X4Z',
    kind="file",
    file_id="file_01JC3D5F7H9K1M3P5R7T",
)

sessions.threads.list

Primary and delegate threads with their usage. Maps to GET /v1/sessions/{session_id}/threads.

for item in client.sessions.threads.list('sesn_01JC7M2K4P6R8T0V2X4Z'):
    print(item.id if hasattr(item, 'id') else item)

sessions.archive

Close the session. Maps to POST /v1/sessions/{session_id}/archive.

result = client.sessions.archive('sesn_01JC7M2K4P6R8T0V2X4Z')

Conventions

Every method accepts extra_headers, extra_query, extra_body and timeout keyword arguments, and has an async twin on AsyncSyntic. List methods return pages that iterate across all pages automatically.

See the Python SDK overview for installation, errors and retries.