Skip to main content

attach

What it is

attach() is the one-call glue between an Express app and an agent. A single call does the work of four otherwise-separate steps:
  1. Mount the agent’s A2A endpoints on your Express app (expose).
  2. Activate triggers registered on the agent via agent.add_triggers() — webhooks become Express routes, schedules become cron timers, emit triggers become event-bus listeners.
  3. Connect to Svantic (MeshConnector.connect), with automatic retries.
  4. Install SIGTERM / SIGINT handlers that deregister cleanly.
It returns an AgentHandle — a small surface for firing emit triggers and tearing the whole setup down.

When to use it

Use attach() when you’re embedding an agent into a service you already run:
  • You have an existing Express app with middleware, routes, and lifecycle.
  • You want triggers (webhooks, cron, emit) without writing the plumbing.
  • You want a single object (AgentHandle) to own teardown.
For standalone agents that don’t need to share an Express process, prefer new Agent({...}).start() — it’s simpler.

Functional usage

See the Attach to Express and Triggers guides for the end-to-end story.

Signature

AttachConfig

RuntimeTrigger

One trigger definition. Every trigger carries a prompt template (with {{…}} placeholders) that is fired when the trigger matches.

Trigger kinds

  • webhookattach() mounts app.post(trigger.path). The request body is the payload.
  • schedule — fires every minute; runs when the cron expression matches the current minute.
  • emit — listens on an internal event bus. Trigger with handle.emit(event, payload) or handle.ask(event, payload).

AgentHandle

Returned by attach(). attach() installs SIGTERM and SIGINT handlers that call detach() for you; you don’t need to wire signal handling yourself.

Exported helpers

interpolate_prompt(template, payload, payload_map?)

Replace {{key}} placeholders in template with values from payload. When payload_map is provided, values are first extracted via dot-notation (e.g. event.data.customer.id) and flattened. Unknown placeholders are left as-is ({{key}}) so they’re easy to spot in logs.

cron_matches_now(expr, now?)

Returns true when the cron expression matches the given instant (default: now). Supports:
  • * wildcard,
  • single values (5),
  • comma lists (0,15,30,45),
  • ranges (9-17),
  • steps (*/15, 9-17/2),
  • weekday names (MONSUN) in the day-of-week field.
Only 5-field cron (minute hour day-of-month month day-of-week) is supported.

Example

See also