> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usesynth.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/managed-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:

```bash theme={null}
pip install "synth-ai[research]"
export SYNTH_API_KEY="sk_..."
```

```python theme={null}
from synth_ai import SynthClient

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

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

```python theme={null}
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`.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](/managed-research/usage). |
| `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](/managed-research/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.