Enhance README with tool use modes and examples

Added detailed explanations for tool use modes, including examples for open loop and closed loop execution.

Author: jingyun19

README.md

@@ -141,7 +141,74 @@ Because of their special behavior of being preserved on context window overflow,
 
 The Prompt API supports **tool use** via the `tools` option, allowing you to define external capabilities that a language model can invoke in a model-agnostic way. Each tool is represented by an object that includes an `execute` member that specifies the JavaScript function to be called. When the language model initiates a tool use request, the user agent calls the corresponding `execute` function and sends the result back to the model.
 
-Here’s an example of how to use the `tools` option:
+There are 2 tool use modes: with automatic execution (closed loop) and without automatic execution (open loop)
+
+Regardless of with or without automatic execution, the session creation and appending signature are the same. Here’s an example:
+
+```js
+const session = await LanguageModel.create({
+  initialPrompts: [
+    {
+      role: "system",
+      content: `You are a helpful assistant. You can use tools to help the user.`
+    }
+  ],
+  tools: [
+    {
+      name: "getWeather",
+      description: "Get the weather in a location.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          location: {
+            type: "string",
+            description: "The city to check for the weather condition.",
+          },
+        },
+        required: ["location"],
+      },
+    }
+  ]
+});
+```
+
+In this example, the `tools` array defines a `getWeather` tool, specifying its name, description and input schema. 
+
+Few shot examples of tool use can be appended like so:
+
+```js
+await session.append([
+    {role: "user", content: "What is the weather in Seattle?"},
+    {role: "tool-call", content: {type: "tool-call", value: {callID:" get_weather_1", name: "get_weather", arguments: {location:"Seattle"}}},
+    {role: "tool-result", content:  {type: "tool-response", value: {callID: "get_weather_1", name: "get_weather", result: [{type:"object", value: {temperature: "55F", humidity: "67%"}}]}},
+    {role: "assistant", content: "The temperature in Seattle is 55F and humidity is 67%"},
+]);
+```
+
+Note that "role" and "type" now supports "tool-call" and "tool-result". `content.result` is a list of a dictionary of `type` and `value`, where `type` can be `{"text", "image", "audio", "object" }` and `value` is `any`.
+
+#### Open Loop:
+
+Without automatic execution, the API will return a `ToolCall` object with `callId` (a unique identifier of this tool call), `name` (name of the tool), and `arguments` (a dictionary fitting the JSON input schema of the tool's declaration), and client is expected to handle the tool execution and append the tool result back to the session.
+
+Example:
+
+```js
+const result = await session.prompt("What is the weather in Seattle?");
+if (result.type=="tool-call") {
+  if (result.name == "get_weather") {
+    const tool_result = getWeather(result.arguments.location);
+    session.prompt([{role:"tool-result", content: {type: "tool-result", value: {callId: result.callID, name: result.name, result: [{type:"object", value: tool_result}]}}}])
+  }
+}
+```
+
+Note that we always require tool-response to immediately follow tool-call generated by the model.
+
+
+#### Closed Loop:
+
+To enable automatic execution, add a `execute` function for each tool's implementation, and add a `toolUseConfig` to indicate that execution is enabled and pose a max number of tool calls invoked in a single session generation:
 
 ```js
 const session = await LanguageModel.create({
@@ -171,13 +238,14 @@ const session = await LanguageModel.create({
         return JSON.stringify(await res.json());
       },
     }
-  ]
+  ],
+toolUseConfig: {enabled: true, max_tool_calls: 5},
 });
 
 const result = await session.prompt("What is the weather in Seattle?");
 ```
 
-In this example, the `tools` array defines a `getWeather` tool, specifying its name, description, input schema, and `execute` implementation. When the language model determines that a tool call is needed, the user agent invokes the `getWeather` tool's `execute()` function with the provided arguments and returns the result to the model, which can then incorporate it into its response.
+When the language model determines that a tool call is needed, the user agent invokes the `getWeather` tool's `execute()` function with the provided arguments and returns the result to the model, which can then incorporate it into its response.
 
 #### Concurrent tool use