diff --git a/apps/docs/docs/building_in_studio.md b/apps/docs/docs/building_in_studio.md new file mode 100644 index 00000000..4e3664ad --- /dev/null +++ b/apps/docs/docs/building_in_studio.md @@ -0,0 +1,90 @@ +# Building Assistants in Studio +This is a guide to building your first assistant on RowBoat Studio, with examples.
+**Prerequisite:** Complete the [installation steps](/installation/) to set up RowBoat Studio. + +## Create the set of initial agents +Copilot can sets up agents for you from scratch. + +### Instruct copilot +First, tell it about the initial set of agents that make up your assistant. + +![Create Initial Agents](img/copilot-create.png) + +Using copilot to create your initial set of agents helps you leverage best practices in formatting agent instructions and connecting agents to each other as a graph, all of which have been baked into copilot. + +### Inspect the agents +Once you apply changes, inspect the agents to see how copilot has built them. Specifically, note the Instructions, Examples and Connected Agents in each agent. + +![Agent Config](img/agent-config.png) + +Also notice that copilot would likely have created a "Hub" agent that is "connected" to other agents. + +![Hub Agent Config](img/hub-config.png) + +### Make changes if needed +Tweak the instructions and examples manually if needed. + +![Edit Agent Manually](img/edit-agent-manually.png) + +## Try an example chat in the playground + +### Chat with the assistant + +The playground is intended to test out the assistant as you build it. The User and Assistant messages represent the conversation that your end-user will have if your assistant is deployed in production. The playground also has debug elements which show the flow of control between different agents in your system, as well as which agent finally responded to the user. + +![Try Chat](img/try-chat.png) + +### Ask copilot questions +You can ask copilot clarifications about the chat, such as why the agents responded a certain way or why an agent was invoked. + +![Copilot Clarifications](img/copilot-clarifications.png) + +## Add tools to agents +Copilot can help you add tools to agents. + +#### Instruct copilot to add tools +![Add Tool](img/add-tool.png) + +![Example Tool](img/example-tool.png) + +### Inspect tools and agents +Note how copilot not only creates the tool definitions for you, but also updates the relevant agent instructions to use the tool and connects the tool to the agent. + +![Inspect Agent Tools](img/inspect-agent-tools.png) +![Inspect Agent Tool Connections](img/inspect-agent-tool-connections.png) + +### Debug tool calls in the playground +When agents call tools during a chat in the playground, the tool call parameters and response are available for debugging real-time. For testing purposes, the platform can produce mock tool responses in the playground, without integrating actual tools. + +![Mock Tool Responses](img/mock-tool-responses.png) +![Debug Tool Calls](img/debug-tool-calls.png) + +## Update agent behavior + +Copilot can help you update agent behavior. It is also aware of the current chat in the playground so you can make references to the current chat while instructing copilot to update agents. + +![Update Agent Behavior](img/update-agent-with-copilot.png) + + +Playground: +![Test Updated Agent](img/test-updated-agent.png) + +## Simulate real-world user scenarios +Create a test-bench of real-world scenarios in the simulator. +![Scenarios](img/scenarios.png) + +Run the scenarios as simulated chats betweeen a user (role-played) and the assistant, in the playground. +![Simulation](img/simulate.png) + + + + + + + + + + + + + diff --git a/apps/docs/docs/img/add-tool.png b/apps/docs/docs/img/add-tool.png new file mode 100644 index 00000000..8e85f40f Binary files /dev/null and b/apps/docs/docs/img/add-tool.png differ diff --git a/apps/docs/docs/img/agent-config.png b/apps/docs/docs/img/agent-config.png new file mode 100644 index 00000000..3887294b Binary files /dev/null and b/apps/docs/docs/img/agent-config.png differ diff --git a/apps/docs/docs/img/copilot-clarifications.png b/apps/docs/docs/img/copilot-clarifications.png new file mode 100644 index 00000000..4611015d Binary files /dev/null and b/apps/docs/docs/img/copilot-clarifications.png differ diff --git a/apps/docs/docs/img/copilot-create.png b/apps/docs/docs/img/copilot-create.png new file mode 100644 index 00000000..cf373956 Binary files /dev/null and b/apps/docs/docs/img/copilot-create.png differ diff --git a/apps/docs/docs/img/debug-tool-calls.png b/apps/docs/docs/img/debug-tool-calls.png new file mode 100644 index 00000000..aa0e5dd9 Binary files /dev/null and b/apps/docs/docs/img/debug-tool-calls.png differ diff --git a/apps/docs/docs/img/dev-config.png b/apps/docs/docs/img/dev-config.png new file mode 100644 index 00000000..3010566d Binary files /dev/null and b/apps/docs/docs/img/dev-config.png differ diff --git a/apps/docs/docs/img/edit-agent-manually.png b/apps/docs/docs/img/edit-agent-manually.png new file mode 100644 index 00000000..9c1c679c Binary files /dev/null and b/apps/docs/docs/img/edit-agent-manually.png differ diff --git a/apps/docs/docs/img/example-tool.png b/apps/docs/docs/img/example-tool.png new file mode 100644 index 00000000..851bbb04 Binary files /dev/null and b/apps/docs/docs/img/example-tool.png differ diff --git a/apps/docs/docs/img/hub-config.png b/apps/docs/docs/img/hub-config.png new file mode 100644 index 00000000..0d2c6467 Binary files /dev/null and b/apps/docs/docs/img/hub-config.png differ diff --git a/apps/docs/docs/img/inspect-agent-tool-connections.png b/apps/docs/docs/img/inspect-agent-tool-connections.png new file mode 100644 index 00000000..330466b0 Binary files /dev/null and b/apps/docs/docs/img/inspect-agent-tool-connections.png differ diff --git a/apps/docs/docs/img/inspect-agent-tools.png b/apps/docs/docs/img/inspect-agent-tools.png new file mode 100644 index 00000000..d5b7cd40 Binary files /dev/null and b/apps/docs/docs/img/inspect-agent-tools.png differ diff --git a/apps/docs/docs/img/mock-tool-responses.png b/apps/docs/docs/img/mock-tool-responses.png new file mode 100644 index 00000000..6ac3d4e2 Binary files /dev/null and b/apps/docs/docs/img/mock-tool-responses.png differ diff --git a/apps/docs/docs/img/prod-deploy.png b/apps/docs/docs/img/prod-deploy.png new file mode 100644 index 00000000..fa22f93a Binary files /dev/null and b/apps/docs/docs/img/prod-deploy.png differ diff --git a/apps/docs/docs/img/scenarios.png b/apps/docs/docs/img/scenarios.png new file mode 100644 index 00000000..828b408b Binary files /dev/null and b/apps/docs/docs/img/scenarios.png differ diff --git a/apps/docs/docs/img/simulate.png b/apps/docs/docs/img/simulate.png new file mode 100644 index 00000000..e6aca149 Binary files /dev/null and b/apps/docs/docs/img/simulate.png differ diff --git a/apps/docs/docs/img/test-updated-agent.png b/apps/docs/docs/img/test-updated-agent.png new file mode 100644 index 00000000..4bc09d80 Binary files /dev/null and b/apps/docs/docs/img/test-updated-agent.png differ diff --git a/apps/docs/docs/img/testing-chat.png b/apps/docs/docs/img/testing-chat.png index 270c959a..2f2eef54 100644 Binary files a/apps/docs/docs/img/testing-chat.png and b/apps/docs/docs/img/testing-chat.png differ diff --git a/apps/docs/docs/img/try-chat.png b/apps/docs/docs/img/try-chat.png new file mode 100644 index 00000000..e48520b5 Binary files /dev/null and b/apps/docs/docs/img/try-chat.png differ diff --git a/apps/docs/docs/img/update-agent-with-copilot.png b/apps/docs/docs/img/update-agent-with-copilot.png new file mode 100644 index 00000000..cfa9b514 Binary files /dev/null and b/apps/docs/docs/img/update-agent-with-copilot.png differ diff --git a/apps/docs/docs/installation.md b/apps/docs/docs/installation.md index 541ce9c2..4431f096 100644 --- a/apps/docs/docs/installation.md +++ b/apps/docs/docs/installation.md @@ -53,14 +53,6 @@ Refer to our [Github Readme for Local Development](https://github.com/rowboatlab ![Testing Chat](img/testing-chat.png)
-6. Ask copilot to make minor modifications to one of the agents and apply the changes: -![Update Agent](img/update-agent.png) -
- -7. Test out another chat in the playground to verify the changes: -![Re-Test Chat](img/re-test-chat.png) -
- ### Testing the Chat API You can use the API directly at [http://localhost:3000/api/v1/](http://localhost:3000/api/v1/) diff --git a/apps/docs/docs/quickstart.md b/apps/docs/docs/quickstart.md deleted file mode 100644 index 238bf8e8..00000000 --- a/apps/docs/docs/quickstart.md +++ /dev/null @@ -1,6 +0,0 @@ -# Quick Start -Follow the [installation steps](/installation/) to set up RowBoat Studio, API and SDK. - -## Building your first assistant - -Coming soon. \ No newline at end of file diff --git a/apps/docs/docs/using_the_api.md b/apps/docs/docs/using_the_api.md new file mode 100644 index 00000000..9166a273 --- /dev/null +++ b/apps/docs/docs/using_the_api.md @@ -0,0 +1,273 @@ +# Using the API + +This is a guide on using the HTTP API to power conversations with the assistant created in Studio. + +## Deploy your assistant to production on Studio +![Prod Deploy](img/prod-deploy.png) + +## Obtain API key and Project ID + +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 + +When you provide your Project ID in the API call, RowBoat uses the version of your assistant deployed to production. + +The API takes as input: a) history of all messages till now (system, user, tool and assistant messages) and b) state generated from the previous turn (this is needed because the API does not maintain state on its own). + +The API produces as response: a) assistant responses (user-facing responses or tool calls) for the current and b) the state to be passed to the next turn. + +### Example first turn of a chat + +#### Request + +```bash +curl --location 'http://localhost:3000/api/v1//chat' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer ' \ +--data '{ + "messages": [ + { + "content": "UserID: 345227", + "role": "system" + // Provide context to be passed to all agents in the assistant + // E.g. user identity info (user ID) for logged in users + }, + { + "content": "What is my outstanding balance and how do I make the payment?", + "role": "user" + } + ], + "state": { + "last_agent_name": "Credit Card Hub" + // This the last agent used in the previous turn. + // Set to the "start agent" for first turn of chats + } +}' +``` +#### Response +```json +{ + "messages": [ + { + "role": "assistant", + "sender": "Credit Card Hub", + "content": null, + "created_at": "2025-02-03T05:22:30.194879", + "current_turn": true, + "response_type": "internal", + "tool_calls": [ + { + "function": { + "name": "transfer_to_outstanding_payments", + "arguments": "{\"args\":\"\",\"kwargs\":\"\"}" + }, + "id": "call_SLyQKXt9ZMqnxSqJjo9j1fU5", + "type": "function" + } + ] + }, + { + "tool_name": "transfer_to_outstanding_payments", + "role": "tool", + "content": "{\"assistant\": \"Outstanding Payments\"}", + "tool_call_id": "call_SLyQKXt9ZMqnxSqJjo9j1fU5" + }, + { + "role": "assistant", + "sender": "Outstanding Payments", + "content": null, + "created_at": "2025-02-03T05:22:30.716012", + "current_turn": true, + "response_type": "internal", + "tool_calls": [ + { + "function": { + "name": "get_outstanding_balance", + "arguments": "{\"user_id\":\"345227\"}" + }, + "id": "call_MNAUg7UTszYMt5RL4n5QqUTw", + "type": "function" + } + ] + } + ], + "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" + ], + "internal_tools": [], + "external_tools": [], + "child_functions": [ + "transfer_to_outstanding_payments", + "transfer_to_transaction_disputes", + "transfer_to_rewards_redemption" + ], + "most_recent_parent_name": "", + "parent_function": null + }, + { + "name": "Outstanding Payments", + "instructions": // agent instructions, + "history": [ + // history of agent-relevant messages + // in the same format as "messages" + ], + "internal_tools": [], + "external_tools": [ + "get_outstanding_balance", + "get_saved_credit_card" + ], + "child_functions": [], + "most_recent_parent_name": "", + "parent_function": null + }, + + // other agents - have not yet participated in the conversation + { + "name": "Rewards Redemption", + "instructions": // agent instructions, + "history": [], // + "internal_tools": [], + "external_tools": [], + "child_functions": [], + "most_recent_parent_name": "", + "parent_function": null + }, + { + "name": "Transaction Disputes", + "instructions": // agent instructions, + "history": [], + "internal_tools": [], + "external_tools": [], + "child_functions": [], + "most_recent_parent_name": "", + "parent_function": null + }, + { + "name": "Escalation", + "instructions": // agent instructions, + "history": [], + "internal_tools": [], + "external_tools": [], + "child_functions": [], + "most_recent_parent_name": "", + "parent_function": null + }, + ], + "last_agent_name": "Outstanding Payments" + } +} + +``` + +### Example where the assistant is expecting a tool response +#### Request +```bash +curl --location 'http://localhost:3000/api/v1//chat' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer ' \ +--data '{ + "messages": [ + { + "content": "UserID: 345227", + "role": "system", + }, + { + "content": "What is my outstanding balance and how do I make the payment?", + "role": "user", + }, + { + "content": null, + "role": "assistant", + "sender": "Credit Card Hub", + "tool_calls": [ + { + "function": { + "arguments": "{\"args\":\"\",\"kwargs\":\"\"}", + "name": "transfer_to_outstanding_payments" + }, + "id": "call_SLyQKXt9ZMqnxSqJjo9j1fU5", + "type": "function" + } + ], + "tool_call_id": null, + "tool_name": null, + "response_type": "internal" + }, + { + "content": "{\"assistant\": \"Outstanding Payments\"}", + "role": "tool", + "sender": null, + "tool_calls": null, + "tool_call_id": "call_SLyQKXt9ZMqnxSqJjo9j1fU5", + "tool_name": "transfer_to_outstanding_payments" + }, + { + "content": null, + "role": "assistant", + "sender": "Outstanding Payments", + "tool_calls": [ + { + "function": { + "arguments": "{\"user_id\":\"345227\"}", + "name": "get_outstanding_balance" + }, + "id": "call_MNAUg7UTszYMt5RL4n5QqUTw", + "type": "function" + } + ], + "tool_call_id": null, + "tool_name": null, + "response_type": "internal" + }, + { + "content": "{\"result\":{\"outstanding_balance\":\"$250.00\",\"due_date\":\"2025-02-15\",\"payment_methods\":[\"Credit Card\",\"Bank Transfer\",\"PayPal\"]}}", + "role": "tool", + "sender": null, + "tool_calls": null, + "tool_call_id": "call_MNAUg7UTszYMt5RL4n5QqUTw", + "tool_name": "get_outstanding_balance" + }, + ], + "state": { + // State returned by the API in the previous turn + } +}' +``` +#### Response +```json +{ + "messages": [ + { + "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!", + "created_at": "2025-02-03T06:01:07.451140", + "current_turn": true, + "response_type": "internal", + "role": "assistant", + "sender": "Outstanding Payments" + }, + { + "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!", + "created_at": "2025-02-03T06:01:07.451140", + "current_turn": true, + "response_type": "external", + "role": "assistant", + "sender": "Outstanding Payments >> Post process" + } + ], + "state": { + "agent_data": [ + // Omitted for brevity + ], + "last_agent_name": "Outstanding Payments" + } +} +``` \ No newline at end of file diff --git a/apps/docs/docs/using_the_sdk.md b/apps/docs/docs/using_the_sdk.md new file mode 100644 index 00000000..a15f82ae --- /dev/null +++ b/apps/docs/docs/using_the_sdk.md @@ -0,0 +1,81 @@ +# Using the Python SDK + +This is a guide on using the RowBoat Python SDK as an alternative to the [RowBoat HTTP API](/using_the_api) to power conversations with the assistant created in Studio. + +## Prerequisites +- [Deploy your assistant to production](/using_the_api/#deploy-your-assistant-to-production-on-studio) and [obtain your API key and Project ID](/using_the_api/#obtain-api-key-and-project-id) +- ``` pip install rowboat ``` + +## Usage + +### Basic Usage + +Initialize a client and use the chat method directly: + +```python +from rowboat import Client +from rowboat.schema import UserMessage, SystemMessage + +# Initialize the client +client = Client( + host="", + project_id="", + api_key="" +) + +# Create messages +messages = [ + SystemMessage(role='system', content="You are a helpful assistant"), + UserMessage(role='user', content="Hello, how are you?") +] + +# Get response +response_messages, state = client.chat(messages=messages) +print(response_messages[-1].content) + +# For subsequent messages, include previous messages and state +messages.extend(response_messages) +messages.append(UserMessage(role='user', content="What's your name?")) +response_messages, state = client.chat(messages=messages, state=state) +``` + +### Using Tools + +The SDK supports function calling through tools: + +```python +def weather_lookup(city_name: str) -> str: + return f"The weather in {city_name} is 22°C." + +# Create a tools dictionary +tools = { + 'weather_lookup': weather_lookup +} + +# Use tools with the chat method +response_messages, state = client.chat( + messages=messages, + tools=tools +) +``` + +### Stateful Chat (Convenience Wrapper) + +For simpler use cases, the SDK provides a `StatefulChat` class that maintains conversation state automatically: + +```python +from rowboat import StatefulChat + +# Initialize stateful chat +chat = StatefulChat( + client, + tools=tools, + system_prompt="You are a helpful assistant." +) + +# Simply send messages and get responses +response = chat.run("Hello, how are you?") +print(response) +# I'm good, thanks! How can I help you today? +``` + diff --git a/apps/docs/mkdocs.yml b/apps/docs/mkdocs.yml index 02bdb523..59ced38b 100644 --- a/apps/docs/mkdocs.yml +++ b/apps/docs/mkdocs.yml @@ -9,4 +9,6 @@ nav: - Open Source License: license.md - Getting started: - Installation: installation.md - - Quickstart: quickstart.md \ No newline at end of file + - Building in Studio: building_in_studio.md + - Using the API: using_the_api.md + - Using the SDK: using_the_sdk.md \ No newline at end of file diff --git a/apps/python-sdk/README.md b/apps/python-sdk/README.md index b63e3786..f6e3fab3 100644 --- a/apps/python-sdk/README.md +++ b/apps/python-sdk/README.md @@ -81,18 +81,4 @@ chat = StatefulChat( response = chat.run("Hello, how are you?") print(response) # I'm good, thanks! How can I help you today? -``` - -## API Reference - -### Client - -The `Client` class handles communication with the Rowboat API. - -```python -Client(host: str, project_id: str, api_key: str) -``` - -### StatefulChat - -The ` \ No newline at end of file +``` \ No newline at end of file