API Reference

Complete Python SDK API documentation

Client

The main interface for interacting with the Rowboat API.

Constructor

Create a new client instance:

from rowboat.client import Client

client = Client(
    host="https://api.rowboat.dev",
    projectId="your-project-id",
    apiKey="your-api-key"
)

Parameters

host · string · required

The Rowboat API host URL (e.g., https://api.rowboat.dev)

projectId · string · required

Your Rowboat project ID from the dashboard

apiKey · string · required

Your Rowboat API key for authentication

Methods

run_turn()

Execute a single conversation turn with the agent.

result = client.run_turn(
    messages=[UserMessage(role='user', content="Hello!")],
    conversationId="conv_123",
    mockTools={"tool_name": "mock response"}
)

Parameters

messages · List[ApiMessage] · required

List of messages to send to the agent. Must include at least one message.

Supported message types:

• UserMessage
• SystemMessage
• AssistantMessage
• AssistantMessageWithToolCalls
• ToolMessage

conversationId · string

The conversation ID from a previous turn. Omit to start a new conversation.

Used to maintain context across multiple turns in a conversation.

mockTools · Dict[str, str]

Dictionary mapping tool names to mock responses.

Use this to test agent behavior without executing real tools:

mockTools={
    "weather_lookup": "Sunny and 72°F",
    "calculator": "42"
}

Returns

ApiResponse · object

The API response containing the conversation ID and turn output.

conversationId · string

The conversation ID. Use this for subsequent turns to maintain context.

turn · Turn

The turn object containing the agent’s response.

id · string

Unique identifier for this turn.

output · List[ApiMessage]

List of output messages from the agent. The last message typically contains the agent’s response.

Raises

• ValueError: Raised when the API returns a non-200 status code

Example

try:
    result = client.run_turn(
        messages=[UserMessage(role='user', content="Hello")]
    )
    print(result.turn.output[-1].content)
    print("Conversation ID:", result.conversationId)
except ValueError as e:
    print(f"API Error: {e}")

Message Types

All message types are imported from rowboat.schema.

UserMessage

Represents a message from the end user.

from rowboat.schema import UserMessage

message = UserMessage(
    role='user',
    content="What's the weather today?"
)

Fields

role · Literal['user'] · required

Must be 'user'

content · string · required

The message content from the user

SystemMessage

Provides system instructions or context to the agent.

from rowboat.schema import SystemMessage

message = SystemMessage(
    role='system',
    content="You are a helpful weather assistant."
)

Fields

role · Literal['system'] · required

Must be 'system'

content · string · required

The system instruction or context

AssistantMessage

Represents a response from the agent.

from rowboat.schema import AssistantMessage

message = AssistantMessage(
    role='assistant',
    content="The weather is sunny and 72°F.",
    responseType='external',
    agenticName='weather-bot'
)

Fields

role · Literal['assistant'] · required

Must be 'assistant'

content · string · required

The assistant’s response message

responseType · Literal['internal', 'external'] · required

The type of response:

• 'internal': Internal agent reasoning (not shown to user)
• 'external': User-facing response

agenticName · string

Optional name identifier for the agent

AssistantMessageWithToolCalls

Represents an assistant message that includes tool calls.

from rowboat.schema import AssistantMessageWithToolCalls, ToolCall, FunctionCall

message = AssistantMessageWithToolCalls(
    role='assistant',
    content="Let me check the weather for you.",
    toolCalls=[
        ToolCall(
            id='call_123',
            type='function',
            function=FunctionCall(
                name='weather_lookup',
                arguments='{"city": "San Francisco"}'
            )
        )
    ],
    agenticName='weather-bot'
)

Fields

role · Literal['assistant'] · required

Must be 'assistant'

content · string

Optional message content

toolCalls · List[ToolCall] · required

List of tool calls made by the assistant

agenticName · string

Optional name identifier for the agent

ToolMessage

Represents the result of a tool execution.

from rowboat.schema import ToolMessage

message = ToolMessage(
    role='tool',
    content='{"temperature": 72, "condition": "sunny"}',
    toolCallId='call_123',
    toolName='weather_lookup'
)

Fields

role · Literal['tool'] · required

Must be 'tool'

content · string · required

The tool execution result (typically JSON string)

toolCallId · string · required

The ID of the tool call this message responds to

toolName · string · required

The name of the tool that was executed

Type Definitions

ToolCall

Represents a request to execute a tool.

from rowboat.schema import ToolCall, FunctionCall

tool_call = ToolCall(
    id='call_123',
    type='function',
    function=FunctionCall(
        name='weather_lookup',
        arguments='{"city": "San Francisco"}'
    )
)

Fields

id · string · required

Unique identifier for this tool call

type · Literal['function'] · required

Must be 'function'

function · FunctionCall · required

The function call details

FunctionCall

Contains details about a function to be called.

from rowboat.schema import FunctionCall

function_call = FunctionCall(
    name='weather_lookup',
    arguments='{"city": "San Francisco"}'
)

Fields

name · string · required

The name of the function to call

arguments · string · required

JSON string containing the function arguments

Turn

Represents a single conversation turn.

from rowboat.schema import Turn

turn = Turn(
    id='turn_123',
    output=[AssistantMessage(...)]
)

Fields

id · string · required

Unique identifier for this turn

output · List[ApiMessage] · required

List of messages generated during this turn

ApiRequest

The request payload sent to the API.

from rowboat.schema import ApiRequest

request = ApiRequest(
    conversationId='conv_123',
    messages=[UserMessage(role='user', content='Hello')],
    mockTools={'tool': 'response'}
)

Fields

conversationId · string

Optional conversation ID to continue an existing conversation

messages · List[ApiMessage] · required

List of messages to send

mockTools · Dict[str, str]

Optional mock tool responses for testing

ApiResponse

The response received from the API.

from rowboat.schema import ApiResponse

response = ApiResponse(
    conversationId='conv_123',
    turn=Turn(...)
)

Fields

conversationId · string · required

The conversation ID (use for subsequent turns)

turn · Turn · required

The turn data containing the agent’s response

Complete Example

Here’s a comprehensive example using the full API:

from rowboat.client import Client
from rowboat.schema import (
    UserMessage,
    SystemMessage,
    ApiResponse
)
import os

# Initialize client
client = Client(
    host=os.getenv("ROWBOAT_HOST", "https://api.rowboat.dev"),
    projectId=os.getenv("ROWBOAT_PROJECT_ID"),
    apiKey=os.getenv("ROWBOAT_API_KEY")
)

def chat(user_message: str, conversation_id: str = None) -> ApiResponse:
    """Send a message and return the response."""
    try:
        result = client.run_turn(
            messages=[
                SystemMessage(
                    role='system',
                    content='You are a helpful assistant.'
                ),
                UserMessage(
                    role='user',
                    content=user_message
                )
            ],
            conversationId=conversation_id
        )
        return result
    except ValueError as e:
        print(f"API Error: {e}")
        raise

# Start conversation
result = chat("What can you help me with?")
print("Assistant:", result.turn.output[-1].content)
conv_id = result.conversationId

# Continue conversation
result = chat("Tell me about your capabilities.", conv_id)
print("Assistant:", result.turn.output[-1].content)

Error Handling

The SDK raises ValueError when the API returns an error:

try:
    result = client.run_turn(
        messages=[UserMessage(role='user', content='Hello')]
    )
except ValueError as e:
    # Handle API errors
    print(f"Error: {e}")
    # Error format: "Error: {status_code} - {response_text}"

Common error scenarios:

• 401 Unauthorized: Invalid API key
• 404 Not Found: Invalid project ID or endpoint
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server-side error

Type Safety

All classes use Pydantic for runtime type validation:

from pydantic import ValidationError
from rowboat.schema import UserMessage

try:
    # This will raise a ValidationError
    message = UserMessage(role='invalid', content='Hello')
except ValidationError as e:
    print(e)