> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Message builder

# MessageBuilder

```typescript theme={null}
import { MessageBuilder } from '@svantic/sdk';
```

## What it is

`MessageBuilder` is a fluent builder for A2A `Message` objects — the envelope that carries a user prompt plus any structured data (files, session context, form submissions, execution context) to a remote agent. An A2A message is usually two parts: a `TextPart` with the prompt and a `DataPart` with metadata. The builder makes assembling that second part ergonomic so you don't hand-write DataPart JSON every time.

## When to use it

* You're calling another agent with a file attachment (PDF, image, document).
* You're continuing a conversation (`with_context_id`) and need to stay on the same session.
* You're replying to a form Svantic emitted (`with_action_data`).
* You need to route directly to a specific agent type (`with_target_agent`) or hand the platform a learner-grade execution context.

For plain text with no metadata, call `remote.send(text)` or `remote.send_stream(text)` instead — there's nothing to build.

## Functional usage

```typescript theme={null}
import { MessageBuilder, RemoteAgent } from '@svantic/sdk';

const invoice_agent = await RemoteAgent.connect(
  'https://api.svantic.com/agents/invoice-agent',
);

// 1. Start with the user-facing prompt.
const msg = new MessageBuilder('Summarize this invoice and flag anything unusual')
  // 2. Keep this turn on an existing conversation.
  .with_context_id(session_id)
  // 3. Give the agent extra situational data.
  .with_context({ tenant: 'acme', requester: 'finance-team' })
  // 4. Attach a file. Prefer file_id (from POST /files/upload) over inline bytes.
  .with_file({
    name: 'march-2025.pdf',
    mime_type: 'application/pdf',
    size: 180_240,
    file_id: uploaded_file_id,
  })
  // 5. Finalize into an A2A Message.
  .build();

// 6. Send and stream.
for await (const event of invoice_agent.send_stream_message(msg)) {
  render(event);
}
```

The builder adds the `DataPart` only if at least one metadata-carrying method was called — plain text passes through as a one-part message.

## Constructor

```typescript theme={null}
new MessageBuilder(text: string)
```

`text` is the user-facing message string. It lands in the first `TextPart` of the resulting message.

## Fluent methods

Every builder method returns `this`, so calls chain.

| Method                                  | Purpose                                                                                                                                                   |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `with_context_id(id)`                   | Continue an existing A2A conversation. Typically the Svantic `session_id`.                                                                                |
| `with_context(ctx)`                     | Attach a free-form object describing the caller's environment (page URL, datasource, active document, …). Forwarded to the remote handler on `context`.   |
| `with_target_agent(name)`               | Route directly to a specific agent, bypassing the orchestrator.                                                                                           |
| `with_yolo_mode(yolo)`                  | When `true`, tells the platform to auto-approve any plan the agent generates. Off by default.                                                             |
| `with_action_data(data)`                | Attach `key: value` form-submission data. Used when the user is replying to an A2UI form.                                                                 |
| `with_file(file)` / `with_files(files)` | Attach one or more [`FilePayload`](./types#filepayload) objects. Prefer setting `file_id` (from the platform's file-upload endpoint) over inlining bytes. |
| `with_execution_context(ctx)`           | Attach a structured [`ExecutionContext`](./types#executioncontext) for the learner.                                                                       |

## Terminal method

### `build(): Message`

Returns an A2A `Message`. The message has:

* One `TextPart` carrying the constructor text.
* One `DataPart` (added only if any metadata-carrying builder method was called) with `{ context, target_agent, yolo_mode, action_data, files, execution_context }` — each key present only when set.
* A fresh `messageId` (UUID v4).
* `role: 'user'`.
* `contextId` when `with_context_id` was called.

## Example

```typescript theme={null}
import { MessageBuilder, RemoteAgent } from '@svantic/sdk';

const invoice_agent = await RemoteAgent.connect('https://invoice.example.com');

const msg = new MessageBuilder('Summarize this invoice')
  .with_context_id(session_id)
  .with_context({ tenant: 'acme' })
  .with_file({
    name: 'march.pdf',
    mime_type: 'application/pdf',
    size: 180_240,
    file_id: 'file_abc123',
  })
  .build();

for await (const event of invoice_agent.send_stream_message(msg)) {
  console.log(event);
}
```