apunkt/rowboat
1
0
Fork 0
mirror of https://github.com/rowboatlabs/rowboat.git synced 2026-04-27 01:16:23 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update docs and simplify sdk

Browse source
This commit is contained in:
Ramnique Singh 2025-04-10 00:24:47 +05:30
parent c338ec4dec
commit 97feb71869
10 changed files with 265 additions and 446 deletions
Download patch file Download diff file Expand all files Collapse all files

293
apps/docs/docs/using_the_api.md
View file

@ -10,27 +10,27 @@ This is a guide on using the HTTP API to power conversations with the assistant
Generate API keys via the developer configs in your project. Copy the Project ID from the same page.
![Developer Configs](img/dev-config.png)
## Call the API
## API Endpoint
When you provide your Project ID in the API call, RowBoat uses the version of your assistant deployed to production.
```
POST <HOST>/api/v1/<PROJECT_ID>/chat
```
**Request parameters:**
Where:
- `messages`: history of all messages in the conversation till now (system, user, tool and assistant messages)
- `state`: generated from the previous turn (this is needed because the API does not maintain state on its own)
- For self-hosted: `<HOST>` is `http://localhost:3000`
**Response parameters:**
## Authentication
- `messages`: assistant responses for the current turn (the last message in `messages` is either the user-facing response or a tool call by the assistant)
- `state`: to be passed to the next turn
Include your API key in the Authorization header:
### API Host
- For the open source installation, the `<HOST>` is [http://localhost:3000](http://localhost:3000)
- When using the hosted app, the `<HOST>` is [https://app.rowboatlabs.com](https://app.rowboatlabs.com)
### Example first turn of a chat
```
Authorization: Bearer <API_KEY>
```
#### Request
## Examples
### First Turn
```bash
curl --location '<HOST>/api/v1/<PROJECT_ID>/chat' \
@ -38,206 +38,129 @@ curl --location '<HOST>/api/v1/<PROJECT_ID>/chat' \
--header 'Authorization: Bearer <API_KEY>' \
--data '{
"messages": [
{
"role": "system",
"content": "UserID: 345227"
// Provide context to be passed to all agents in the assistant
// E.g. user identity info (user ID) for logged in users
},
{
"role": "user",
"content": "What is my outstanding balance and how do I make the payment?"
"content": "Hello, can you help me?"
}
],
"state": {
"last_agent_name": "Credit Card Hub"
// Last agent used in the previous turn
// Set to the "start agent" for first turn of chats
}
"state": null
}'
```
#### Response
Response:
```json
{
"messages": [
{
"sender": "Credit Card Hub",
"role": "assistant",
"response_type": "internal",
"content": null,
"current_turn": true,
"tool_calls": [
{
"function": {
// Internal tool calls are used to transfer between agents
"name": "transfer_to_outstanding_payments",
"arguments": "{\"args\":\"\",\"kwargs\":\"\"}"
},
"id": "call_SLyQKXt9ZMqnxSqJjo9j1fU5",
"type": "function"
}
]
},
{
"role": "tool",
"tool_name": "transfer_to_outstanding_payments",
"content": "{\"assistant\": \"Outstanding Payments\"}",
"tool_call_id": "call_SLyQKXt9ZMqnxSqJjo9j1fU5"
},
{
// Last message in response messages is a tool call
"sender": "Outstanding Payments",
"role": "assistant",
"response_type": "internal",
"content": null,
"current_turn": true,
"tool_calls": [
{
"function": {
"name": "get_outstanding_balance",
"arguments": "{\"user_id\":\"345227\"}"
},
"id": "call_MNAUg7UTszYMt5RL4n5QqUTw",
"type": "function"
}
]
"content": "Hello! Yes, I'd be happy to help you. What can I assist you with today?",
"agenticResponseType": "external"
}
],
"state": {
"agent_data": [
// Agents that were involved in this turn
{
"name": "Credit Card Hub",
"instructions": "// agent instructions",
"history": [
// History of agent-relevant messages
// in the same format as "messages"
],
"child_functions": [
"transfer_to_outstanding_payments",
"transfer_to_transaction_disputes",
"transfer_to_rewards_redemption"
],
},
{
"name": "Outstanding Payments",
"instructions": // Agent instructions,
"history": [
// History of agent-relevant messages
// in the same format as "messages"
],
"external_tools": [
"get_outstanding_balance",
"get_saved_credit_card"
],
},
// Other agents - have not yet participated in the conversation
{
"name": "Rewards Redemption",
"instructions": // Agent instructions,
"history": [], //
}
],
"last_agent_name": "Outstanding Payments"
"last_agent_name": "MainAgent"
}
}
```
### Example where the assistant is expecting a tool response
#### Request
### Subsequent Turn
Notice how we include both the previous messages and the state from the last response:
```bash
curl --location 'http://localhost:3000/api/v1/<PROJECT_ID>/chat' \
curl --location '<HOST>/api/v1/<PROJECT_ID>/chat' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_KEY>' \
--data '{
"messages": [
{
"role": "system",
"content": "UserID: 345227"
"role": "user",
"content": "Hello, can you help me?"
},
{
"role": "assistant",
"content": "Hello! Yes, I'd be happy to help you. What can I assist you with today?",
"agenticResponseType": "external"
},
{
"role": "user",
"content": "What is my outstanding balance and how do I make the payment?"
},
{
"sender": "Credit Card Hub",
"role": "assistant",
"response_type": "internal",
"content": null,
"tool_calls": [
{
"function": {
"arguments": "{\"args\":\"\",\"kwargs\":\"\"}",
"name": "transfer_to_outstanding_payments"
},
"id": "call_SLyQKXt9ZMqnxSqJjo9j1fU5",
"type": "function"
}
],
},
{
"role": "tool",
"tool_name": "transfer_to_outstanding_payments",
"content": "{\"assistant\": \"Outstanding Payments\"}",
"tool_call_id": "call_SLyQKXt9ZMqnxSqJjo9j1fU5"
},
{
"sender": "Outstanding Payments",
"role": "assistant",
"response_type": "internal",
"content": null,
"tool_calls": [
{
"function": {
"arguments": "{\"user_id\":\"345227\"}",
"name": "get_outstanding_balance"
},
"id": "call_MNAUg7UTszYMt5RL4n5QqUTw",
"type": "function"
}
],
},
{
// New message is a tool response to the previous tool call
"role": "tool",
"tool_name": "get_outstanding_balance"
"content": "{\"result\":{\"outstanding_balance\":\"$250.00\",\"due_date\":\"2025-02-15\",\"payment_methods\":[\"Credit Card\",\"Bank Transfer\",\"PayPal\"]}}",
"tool_call_id": "call_MNAUg7UTszYMt5RL4n5QqUTw",
},
],
"state": {
// State returned by the API in the previous turn
}
}'
```
#### Response
```json
{
"messages": [
{
"sender": "Outstanding Payments",
"role": "assistant",
// Response is not user-facing, to enable further post processing
"response_type": "internal",
"content": "Your outstanding balance is $250.00, due by February 15, 2025.\n\nYou have several payment options available, including:\n- **Credit Card**\n- **Bank Transfer**\n- **PayPal**\n\nPlease let me know which option you'd like to use, and I'll guide you through the process!",
"current_turn": true
},
{
"sender": "Outstanding Payments >> Post process",
"role": "assistant",
// Response is user-facing
"response_type": "external",
"content": "Your outstanding balance is $250.00, due by February 15, 2025. \n\nPayment options include:\n- **Credit Card:** You can use your saved Visa card ending in 1234.\n- **Bank Transfer**\n- **PayPal**\n\nLet me know your preferred payment method, and I’ll assist you!",
"current_turn": true,
"content": "What services do you offer?"
}
],
"state": {
"agent_data": [
// Omitted for brevity
],
"last_agent_name": "Outstanding Payments"
"last_agent_name": "MainAgent"
}
}'
```
## API Specification
### Request Schema
```typescript
{
// Required fields
messages: Message[]; // Array of message objects representing the conversation history
state: any; // State object from previous response, or null for first message
// Optional fields
workflowId?: string; // Specific workflow ID to use (defaults to production workflow)
testProfileId?: string; // Test profile ID for simulation
}
```
```
### Message Types
Messages can be one of the following types:
1. System Message
```typescript
{
role: "system";
content: string;
}
```
2. User Message
```typescript
{
role: "user";
content: string;
}
```
3. Assistant Message
```typescript
{
role: "assistant";
content: string;
agenticResponseType: "internal" | "external";
agenticSender?: string | null;
}
```
### Response Schema
```typescript
{
messages: Message[]; // Array of new messages from this turn
state: any; // State object to pass in the next request
}
```
## Important Notes
1. Always pass the complete conversation history in the `messages` array
2. Always include the `state` from the previous response in your next request
3. The last message in the response's `messages` array will be a user-facing assistant message (`agenticResponseType: "external"`)
## Rate Limiting
The API has rate limits per project. If exceeded, you'll receive a 429 status code.
## Error Responses
- 400: Invalid request body or missing/invalid Authorization header
- 403: Invalid API key
- 404: Project or workflow not found
- 429: Rate limit exceeded