Skip to main content

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.

​
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.
MethodPurpose
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);
}