Synth Tag

Delegate a one-off research task, steer the active run, and retrieve a terminal run receipt.

Synth Tag is the session-shaped delegate API for Managed Research. Use it when you want to hand Synth one task from the SDK or MCP, steer the same active run, and retrieve a receipt when the run reaches a terminal state.

Tag v1 is SDK and MCP only. It does not ship Slack, CLI commands, access bundle CRUD, memory, routines, a web console, or automatic Factory linking.

When to use Tag

Use Tag for one-off delegated work:

• investigate a benchmark failure
• summarize a repository or run result
• produce a short research note with a definition of done
• give an MCP-enabled agent a smaller task surface than the full Factory API

Use Research Factories when you need a durable program with repeated Efforts, scheduling, status projections, and follow-up runs.

Install and authenticate

Install the Research SDK package selected in the release checklist:

pip install "synth-ai[research]"
export SYNTH_API_KEY="sk_..."

from synth_ai import SynthClient

client = SynthClient()
tag = client.research.factories.tag

For local development against a slot backend, pass the backend URL explicitly:

client = SynthClient(
    api_key="sk_...",
    base_url="http://127.0.0.1:8001",
)

Create a session

sessions.create creates a Tag session, starts its bound Managed Research run, and returns both session_id and run_id.

session = client.research.factories.tag.sessions.create(
    "Investigate why the smoke run failed and summarize the smallest fix.",
    definition_of_done="Return a root-cause note with evidence and next action.",
    timebox_seconds=300,
)

print(session.session_id)
print(session.run_id)
print(session.status.value)

If you omit scope_id, the backend creates or reuses the default Tag scope for the organization.

Steer the active run

Use sessions.messages.send to add guidance to the same Tag session. A successful steer keeps the same run_id; it does not start another run.

session = client.research.factories.tag.sessions.messages.send(
    session.session_id,
    "Keep the final answer under 100 words and include the run receipt.",
)

assert session.run_id is not None

Poll for the receipt

sessions.get returns coarse status: queued, running, done, or failed. When the session is terminal, the receipt includes the run id, terminal state, run URL, and either artifact URLs or an explicit empty-artifact reason.

import time

while session.status.value not in {"done", "failed"}:
    time.sleep(10)
    session = client.research.factories.tag.sessions.get(session.session_id)

receipt = session.receipt
print(receipt.state)
print(receipt.run_id)
print(receipt.run_url)
print(receipt.artifact_urls or receipt.artifact_empty_reason)

Smoke script

The synth-ai package includes examples/tag_delegate_smoke.py for delegate, steer, and receipt checks:

uv run python examples/tag_delegate_smoke.py \
  --backend-url http://127.0.0.1:8001 \
  --request "Summarize what Synth Tag v1 proves in one paragraph." \
  --timebox-seconds 120 \
  --wait

The synth-dev wrapper loads SYNTH_API_KEY from the local synth-ai/.env and maps slot ports:

cd /path/to/synth-dev
./scripts/tag_smoke.sh --instance slot2 --timeout-seconds 300 --timebox-seconds 120

MCP tools

Tag tools intentionally use tag_* names so delegate sessions do not collide with the lower-level smr_* Factory and run-control tools.

Tool	Purpose
tag_create_session	Create a Tag session and launch its bound run.
tag_get_session	Read session status and terminal receipt.
tag_send_message	Steer the active session without creating a new run.

Tag vs Factory

Use Tag when…	Use Factory when…
You have one task to delegate now.	You have a recurring or long-lived program.
You want a simple session id, run id, and receipt.	You need Efforts, scheduling, decisions, and status projections.
Your agent needs a small MCP task surface.	Your operator needs the full Factory control plane.

Tag can later link into Factory programs, but v1 treats Factory linking, Gardener, Seraph, routines, and memory as future work.

Limits and errors

Tag uses existing organization-level Managed Research limits. Launch denials surface through the same error classes as normal runs:

HTTP	Meaning	Action
402	Insufficient credits or spend headroom	Check Usage and Budgets.
429	Rate, capacity, or concurrent-run limit	Retry later or reduce parallel launches.
404	Unknown session or scope	Check the session id and API key organization.

See Preflight and Errors for the broader Managed Research launch-denial vocabulary.

Beta scope

Synth Tag v1 ships:

• SDK and MCP delegate/steer/receipt
• default Tag scope per organization
• optional definition of done stored on the session and passed into the run
• run receipts with artifact pointers or explicit empty-artifact reasons

Coming later: CLI, access bundles, live checklist items, memory, routines, Factory program linking, and messaging adapters such as Slack or Linear.