sail-voyage

Sail Voyage

Use this skill to instrument any background or long-running agent run on Sail Voyages so the dashboard shows its trajectory. Sail provides the flight recorder; it does not run the agent for you.

This is the entrypoint skill. Start here whether you are smoke-testing a one-off run or shipping a polished, repeatable production workflow such as deep research, code review, eval generation, support triage, migration analysis, or scheduled monitoring. The same run → agent → span → event loop covers all of them; you scale detail up, not skills. (run() owns the terminal lifecycle — completed on clean exit, failed on exception.)

For two adjacent concerns, reach for a focused sibling skill:

• migrating an existing app or workflow to Sail → sail-migrate
• attributing Sail inference model calls to the active agent/span → sail-inference-with-voyage
• a Voyage that looks wrong in the dashboard → sail-voyage-debugging

For the full multi-agent attribution model (name, role, and slug semantics, per-agent pitfalls, and dashboard verification), see references/multi-agent.md. For a complete runnable skeleton, see references/minimal-example.md.

The Voyages model

• A Voyage is one concrete run (one trace).
• A series is the recurring workflow, identified by the user-facing name.
• A version is a positive integer for meaningful workflow changes.
• The dashboard starts from /voyages, groups by series, and links each run to /{env}/voyages/{voyage_id}.
• voyage_series_id is internal. Do not ask users to provide it, log it, or build URLs around it.

If you have used an LLM/agent tracing tool, the vocabulary maps cleanly:

Quickstart: a minimal Voyage

The smallest useful Voyage: one run() block at task entry, with the work in decorated agent/span functions. run() creates the Voyage on enter and owns the terminal lifecycle: voyage.completed on clean exit, voyage.failed + re-raise on an exception.

import sail

@sail.agent("Executor")
@sail.span()  # span named after the function
def run_task(step):
    sail.voyage.event("task.started", payload={"step": step})
    # ... do work ...

with sail.voyage.run(
    name="repo-repair",
    version=1,
    metadata={"repo": "example-org/example-repo", "task": "eval"},
):
    run_task(1)

Decorators are the default attribution shape. Declare each agent or phase as a function and stack @sail.agent(...) / @sail.span(...) on it (sail.agent and sail.span are top-level re-exports of the module-level helpers). They resolve the current Voyage at call time (module-level decoration before the Voyage exists is fine), support async def fully, raise TypeError on generator functions, and emit a fresh span per call. Model calls and Sailbox execs inside a decorated function auto-attribute to its agent/span (Level 1/2), so most functions need no inline telemetry at all.

For inline steps that aren't function-shaped, use the with form — same frames, same events:

with sail.voyage.run(name="repo-repair", version=1) as voyage:
    with voyage.agent("Executor"):
        with voyage.span("run task"):
            voyage.event("task.started", payload={"step": 1})

create()/attach() remain the primitives for split-lifecycle controllers — then you own calling complete() or fail() exactly once before exit.

Auto-spans (Level 1/2): Sail inference calls and Sailbox execs made with no active span get a real, timed span synthesized automatically, named after the calling function when derivable (fetch_sources, not "model call"). Synthesized spans carry an _auto payload marker and render with an "auto" chip. Explicit agents/spans always win — synthesis only covers what you didn't declare. Kill switch: SAIL_VOYAGE_AUTO_SPANS=0. Underscore-prefixed top-level payload keys are reserved for the SDK.

Use module-level sail.voyage.* helpers for the current Voyage, or keep the returned voyage object when multiple handles are present. The current Voyage is context-local (Python contextvars) with a process-wide fallback: concurrent tasks that each create()/attach() their own Voyage keep their own attribution for module-level helpers and sail.inference.* wrappers, while a context that never started one uses the process's most recently started Voyage. When one context juggles several Voyages, route everything through the handles: use voyage.event(...)/voyage.span(...) for telemetry AND pass voyage= to every sail.inference.* call (the wrappers default to the current Voyage, not the handle whose span you are inside). Sailbox.exec() attribution follows the current Voyage and cannot take a handle — do not run execs for a non-current Voyage; serialize them or accept attribution to whichever Voyage is current. If the task controls a Sailbox, bind it: sail.voyage.run(..., sailbox_id=sb.sailbox_id) (or create(...)).

Production shape

Every production Voyage should answer these in the dashboard:

1. What recurring workflow is this?
2. Which workflow version ran?
3. Which agent owned each important decision or side effect?
4. Which model calls and Sailbox execs happened under each span?
5. What did the run produce?
6. Did it complete, fail, or get cancelled?

Map those questions onto the SDK like this:

import os
import sail


@sail.agent("Planner", role="planner")
@sail.span("scope research question")
def plan():
    sail.voyage.event("research.scope.selected", payload={"question_count": 4})


@sail.agent("Researcher", role="researcher")
@sail.span("collect sources")
def research():
    # The inference call auto-attributes to this agent/span (Level 1/2) —
    # no inline with-block needed.
    response = sail.inference.responses.create(
        model="zai-org/GLM-5.1-FP8",
        input="Collect a concise source map for the topic.",
        background=False,
        timeout=120,
    )
    sail.voyage.event("research.sources.collected", payload={"response_id": response["id"]})


@sail.agent("Publisher", role="publisher")
@sail.span("write final artifact")
def publish():
    sail.voyage.event(
        "artifact.report.ready",
        payload={
            "artifact_type": "html_report",
            "path_hint": "/tmp/voyage-output/report.html",
            "summary": "Draft report generated and ready for operator review.",
        },
    )


with sail.voyage.run(
    name="deep-research",
    version=3,
    metadata={
        "topic": "public launch plan for Sail Voyages",
        "source": "blog-demo",
        "commit": os.environ.get("GITHUB_SHA"),
    },
):
    plan()
    research()
    publish()
# No complete()/fail() needed: run() emits the terminal state. Use
# sail.voyage.create() only when start and end cannot share a code block
# (daemons, notebooks, framework callbacks) — then YOU own complete()/fail().

Choose the series name

name is the stable user-facing series identity. It should describe the workflow, not the input, run date, environment, Sailbox, branch, or Voyage id.

Good names: deep-research, code-review, nightly-backend-eval, support-triage, release-risk-scan.

Poor names: deep-research-2026-06-05, voy_v7f..., prod-run, github-pr-2381, kavin-test-2.

Put changing run context in metadata, not in name:

with sail.voyage.run(
    name="code-review",
    version=4,
    metadata={"repo": "example-org/example-repo", "pr_number": 42, "head_sha": "abc123"},
) as voyage:
    ...

Names are not lowercased, slugified, or whitespace-normalized by the product contract. Code Review and code-review are different series. Pick one spelling and keep it stable.

Choose the version

version is a workflow-definition dimension. Increment it when behavior meaningfully changes:

• prompt or system instruction changes
• model/provider changes
• tool set changes
• Sailbox image or command harness changes
• agent topology changes
• validation rubric changes
• output format changes

During initial development, stay on version=1 — debugging iterations in one sitting are not workflow versions; bump only once a harness is recurring and a change is meant to be compared against its predecessor.

Do not increment it for: a new PR, repo, issue, customer, topic, or dataset; a date or schedule tick; a rerun of the same workflow; a new Sailbox id; a new Voyage id; or a failed run you retry with the same code.

Skipped versions are valid; versions need not be contiguous because they may align with an external workflow release system. If omitted, version defaults to 1. For public demos, set an explicit version so the dashboard tells readers which iteration produced the run.

Design agents for dashboard readability

Agents are customer-facing ownership labels. Declare one with just its display name — with voyage.agent("Researcher"): — and the stable attribution key is derived automatically. role= is optional taxonomy for cross-workflow filtering; slug= (advanced) pins the attribution key if you later rename the display name. Use a small, stable set that matches real responsibility boundaries.

| Agent name | Role | Own

Content truncated.