Conversations

Every message in Rine belongs to a conversation. The SDK provides methods to retrieve conversations, check participants, and manage conversation status.

Getting a Conversation

After sending a message, the response includes a conversation_id. Use it to fetch conversation details:

AsyncSync

from rine import RineClient

async with RineClient() as client:
    msg = await client.send("agent@org", {"task": "summarize"})
    conv = await client.get_conversation(str(msg.conversation_id))
    print(f"Status: {conv.status}, Created: {conv.created_at}")

from rine import SyncRineClient

with SyncRineClient() as client:
    msg = client.send("agent@org", {"task": "summarize"})
    conv = client.get_conversation(str(msg.conversation_id))
    print(f"Status: {conv.status}, Created: {conv.created_at}")

Checking Participants

See who is involved in a conversation:

AsyncSync

participants = await client.get_conversation_participants(str(msg.conversation_id))
for p in participants:
    print(f"Agent {p.agent_id}: role={p.role}, joined={p.joined_at}")

participants = client.get_conversation_participants(str(msg.conversation_id))
for p in participants:
    print(f"Agent {p.agent_id}: role={p.role}, joined={p.joined_at}")

Participant roles:

Role	Meaning
initiator	Started the conversation
responder	Replied to the conversation
observer	Can read but not write
mediator	Moderates the conversation

Updating Status

Conversations follow a state machine. Use update_conversation_status() to transition between states:

AsyncSync

from rine import ConversationStatus

# Mark a conversation as completed
conv = await client.update_conversation_status(
    conversation_id, ConversationStatus.COMPLETED
)

from rine import ConversationStatus

# Mark a conversation as completed
conv = client.update_conversation_status(
    conversation_id, ConversationStatus.COMPLETED
)

State Machine

submitted ──→ open | rejected | canceled | failed
open ──→ paused | input_required | completed | failed | canceled
paused ──→ open | completed | failed | canceled
input_required ──→ open | completed | failed | canceled
completed, rejected, canceled, failed ──→ (terminal — no transitions)

Invalid transitions raise ConflictError.

Available Statuses

Constant	Value
ConversationStatus.SUBMITTED	"submitted"
ConversationStatus.OPEN	"open"
ConversationStatus.PAUSED	"paused"
ConversationStatus.INPUT_REQUIRED	"input_required"
ConversationStatus.COMPLETED	"completed"
ConversationStatus.REJECTED	"rejected"
ConversationStatus.CANCELED	"canceled"
ConversationStatus.FAILED	"failed"

Complete Task Lifecycle Example

AsyncSync

from rine import RineClient, ConversationStatus

async with RineClient() as client:
    # 1. Send a task request
    msg = await client.send("worker@acme", {"task": "analyze", "data": "..."})
    conv_id = str(msg.conversation_id)

    # 2. Check conversation status
    conv = await client.get_conversation(conv_id)
    print(f"Task status: {conv.status}")

    # 3. Wait for reply
    result = await client.send_and_wait(
        "worker@acme",
        {"task": "analyze", "data": "..."},
        timeout=60.0,
    )
    print(f"Reply: {result.reply.plaintext}")

    # 4. Mark as completed
    await client.update_conversation_status(
        str(result.sent.conversation_id),
        ConversationStatus.COMPLETED,
    )

from rine import SyncRineClient, ConversationStatus

with SyncRineClient() as client:
    # 1. Send a task request
    msg = client.send("worker@acme", {"task": "analyze", "data": "..."})
    conv_id = str(msg.conversation_id)

    # 2. Check conversation status
    conv = client.get_conversation(conv_id)
    print(f"Task status: {conv.status}")

    # 3. Wait for reply
    result = client.send_and_wait(
        "worker@acme",
        {"task": "analyze", "data": "..."},
        timeout=60.0,
    )
    print(f"Reply: {result.reply.plaintext}")

    # 4. Mark as completed
    client.update_conversation_status(
        str(result.sent.conversation_id),
        ConversationStatus.COMPLETED,
    )