# Conversations (/docs/reference/core/conversation)

Part of the [`@tensorpass/aiconnect` reference](/docs/reference/core). The tables are generated from the package's TypeScript source each time the docs are built. Open a row to see its full type.

## runConversation [#runconversation]

Runs the agent loop in the browser: the model answers or asks for tools, the site's tools run, their results go back to the model, until it answers in plain text.

### RunConversation

| Prop              | Type                                                       | Description |
| ----------------- | ---------------------------------------------------------- | ----------- |
| `runConversation` | `(options: ConversationOptions) => Promise<ChatMessage[]>` |             |

It returns the messages the conversation gained: the assistant turns and the tool results, ending with the final assistant answer. It leaves `options.messages` untouched, so append the result to your transcript yourself.

- It lists the tools once, then sends `messages` and the tool definitions to `session.chat`. It sends no [generation options](/docs/reference/core/messages#generationoptions); call `session.chat` directly to set them.
- It runs the tools the model asks for one after the other, in the model's order, and adds each result as a `tool` message.
- A tool that throws becomes a result with the text `Tool error: ` and the error's message, which the model reads.
- A tool runs only when it was offered to the model at that step. A call to any other name gets a `Tool error: ` result and stays out of your tool source. One answer runs `maxToolCalls` tools at most (8 by default), and the calls past it get a `Tool error: ` result.
- It stops when an answer has no tool calls, when no `tools` were given, or after `maxSteps` steps (6 by default). The last step offers no tools, so the model has to conclude. Tool calls in that last answer do not run, and the answer is kept as its text.
- An error from `session.chat`, such as a provider refusal or the visitor stopping the answer in the wallet, rejects the promise.

```ts
const { state } = client;
if (state.status === 'connected') {
  const asked: ChatMessage = { role: 'user', content: 'A calm book for tonight' };
  const added = await runConversation({
    session: state.session,
    tools,
    messages: [{ role: 'system', content: SYSTEM }, asked],
    onText: (delta) => output.append(delta),
  });
  transcript.push(asked, ...added);
}
```

## ConversationOptions [#conversationoptions]

### ConversationOptions

| Prop            | Type                                                      | Description |
| --------------- | --------------------------------------------------------- | ----------- |
| `session`       | `ProviderSession`                                         |             |
| `messages`      | `ChatMessage[]`                                           |             |
| `tools?`        | `ToolSource \| undefined`                                 |             |
| `maxSteps?`     | `number \| undefined`                                     |             |
| `maxToolCalls?` | `number \| undefined`                                     |             |
| `signal?`       | `AbortSignal \| undefined`                                |             |
| `guard?`        | `ChatGuard \| undefined`                                  |             |
| `onText?`       | `((delta: string) => void) \| undefined`                  |             |
| `onToolCall?`   | `((call: ToolCall) => void) \| undefined`                 |             |
| `onToolResult?` | `((call: ToolCall, result: string) => void) \| undefined` |             |

- **session.** The `session` of a `connected` state.
- **messages.** The conversation so far, system prompt first.
- **tools.** The tool source. Without it, the model answers once.
- **maxSteps.** The number of model calls at most. The default is 6.
- **maxToolCalls.** The number of tools one answer of the model runs at most. The default is 8.
- **signal.** Passed to `session.chat` on each step, and checked before each tool runs. With the wallet's session, aborting it stops the chat in AI Wallet, and the promise rejects with the signal's reason.
- **onText**, **onToolCall**, **onToolResult.** The [hooks](#conversationhooks).

```ts
const controller = new AbortController();
stopButton.onclick = () => controller.abort();

const added = await runConversation({ session: state.session, tools, messages, maxSteps: 3, signal: controller.signal });
```

## ConversationHooks [#conversationhooks]

### ConversationHooks

| Prop            | Type                                                      | Description |
| --------------- | --------------------------------------------------------- | ----------- |
| `onText?`       | `((delta: string) => void) \| undefined`                  |             |
| `onToolCall?`   | `((call: ToolCall) => void) \| undefined`                 |             |
| `onToolResult?` | `((call: ToolCall, result: string) => void) \| undefined` |             |

- **onText.** Each piece of the answer's text as it streams, across every step of the loop.
- **onToolCall.** A tool call, before the tool runs.
- **onToolResult.** The same call with its result, after the tool ran or failed.

```ts
await runConversation({
  session: state.session,
  tools,
  messages,
  onToolCall: (call) => showStatus(`Running ${call.name}`),
  onToolResult: (call, result) => renderCards(call.name, result),
});
```

## finalAnswer [#finalanswer]

### FinalAnswer

| Prop          | Type                                                    | Description |
| ------------- | ------------------------------------------------------- | ----------- |
| `finalAnswer` | `(messages: ChatMessage[]) => AssistantMessage \| null` |             |

Returns the last message when it is an assistant message, and `null` otherwise.

```ts
const added = await runConversation({ session: state.session, tools, messages });
const answer = finalAnswer(added)?.content ?? '';
```

## Chat content helpers [#chat-content-helpers]

The functions that read a message's content, as parts or as text, and an image's `data:` URL as its media type and base64 data. AI Wallet's connectors use them in every translation.

### ChatContentHelpers

| Prop           | Type                                                  | Description |
| -------------- | ----------------------------------------------------- | ----------- |
| `contentParts` | `(content: string \| ContentPart[]) => ContentPart[]` |             |
| `textOf`       | `(content: string \| ContentPart[]) => string`        |             |
| `inlineData`   | `(url: string) => InlineData \| null`                 |             |
| `dataUrl`      | `({ mediaType, data }: InlineData) => string`         |             |

- **contentParts(content).** The content as parts. A string becomes one text part, and an empty string none.
- **textOf(content).** The text of the parts joined, without the images.
- **inlineData(url).** The media type and data of a base64 `data:` URL, or `null` for any other URL.
- **dataUrl(data).** The `data:` URL of an `InlineData`.

### InlineData [#inlinedata]

### InlineData

| Prop        | Type     | Description |
| ----------- | -------- | ----------- |
| `mediaType` | `string` |             |
| `data`      | `string` |             |

```ts
const question: UserMessage = {
  role: 'user',
  content: [
    { type: 'text', text: 'What does this label say?' },
    { type: 'image', url: dataUrl({ mediaType: 'image/png', data: PNG_BASE64 }) },
  ],
};

textOf(question.content); // 'What does this label say?'

// An Anthropic image block: inline data when the URL carries it, the URL otherwise.
const blocks = contentParts(question.content).map((part) => {
  if (part.type === 'text') {
    return { type: 'text', text: part.text };
  }
  const inline = inlineData(part.url);
  return inline
    ? { type: 'image', source: { type: 'base64', media_type: inline.mediaType, data: inline.data } }
    : { type: 'image', source: { type: 'url', url: part.url } };
});
```
