MessageBuilder

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

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

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` objects. Prefer setting `file_id` (from the platform’s file-upload endpoint) over inlining bytes.
`with_execution_context(ctx)`	Attach a structured `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

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);
}

Overview

Guides

Reference

Message builder

MessageBuilder

What it is

When to use it

Functional usage

Constructor

Fluent methods

Terminal method

`build(): Message`

Example

​MessageBuilder

​What it is

​When to use it

​Functional usage

​Constructor

​Fluent methods

​Terminal method

​build(): Message

​Example

MessageBuilder

What it is

When to use it

Functional usage

Constructor

Fluent methods

Terminal method

`build(): Message`

Example