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
The Rowboat API host URL (e.g., https://api.rowboat.dev)
Your Rowboat project ID from the dashboard
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
List of messages to send to the agent. Must include at least one message.Supported message types:
UserMessageSystemMessageAssistantMessageAssistantMessageWithToolCallsToolMessage
The conversation ID from a previous turn. Omit to start a new conversation.Used to maintain context across multiple turns in a conversation.
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
The API response containing the conversation ID and turn output.The conversation ID. Use this for subsequent turns to maintain context.
The turn object containing the agent’s response.Unique identifier for this turn.
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
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'
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'
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
Optional name identifier for the agent
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'
List of tool calls made by the assistant
Optional name identifier for the agent
from rowboat.schema import ToolMessage
message = ToolMessage(
role='tool',
content='{"temperature": 72, "condition": "sunny"}',
toolCallId='call_123',
toolName='weather_lookup'
)
Fields
The tool execution result (typically JSON string)
The ID of the tool call this message responds to
The name of the tool that was executed
Type Definitions
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
Unique identifier for this tool call
type
Literal['function']
required
Must be 'function'
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
The name of the function to call
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
Unique identifier for this turn
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
Optional conversation ID to continue an existing conversation
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
The conversation ID (use for subsequent turns)
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}"
- 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)