Skip to main content
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.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

create_session creates a Tag session, starts its bound Managed Research run, and returns both session_id and run_id. 
session = client.research.tag.create_session(
    "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 send_message 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.tag.send_message(
    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

get_session 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.tag.get_session(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 ~/Documents/GitHub/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.
ToolPurpose
tag_create_sessionCreate a Tag session and launch its bound run.
tag_get_sessionRead session status and terminal receipt.
tag_send_messageSteer 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:
HTTPMeaningAction
402Insufficient credits or spend headroomCheck Usage and Budgets.
429Rate, capacity, or concurrent-run limitRetry later or reduce parallel launches.
404Unknown session or scopeCheck 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.