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

# Append to Agent Runs

> Add transcripts and transcript groups to an existing agent run

Use these methods to extend an existing [agent run](/concepts/agent-run) with
additional [transcripts](/concepts/transcript) or transcript groups after the
run has already been ingested — for example, when continuing a long-running
session or attaching follow-up turns to a previously uploaded run.

The new transcripts and groups must reference the target agent run; IDs are
assigned by the server and cannot be set by the caller.

## Append Transcripts

```python theme={null}
from docent import Docent
from docent.data_models import Transcript
from docent.data_models.chat import UserMessage, AssistantMessage

client = Docent()

new_transcripts = [
    Transcript(
        messages=[
            UserMessage(content="Follow-up question"),
            AssistantMessage(content="Follow-up answer"),
        ],
    ),
]

result = client.add_transcripts_to_agent_run(
    collection_id="my-collection-id",
    agent_run_id="run-id-123",
    transcripts=new_transcripts,
)
print(result)
# {"transcripts_added": 1, "transcript_groups_added": 0}
```

To nest the new transcripts under newly-created transcript groups, construct
the group first and reference `group.id` from each transcript's
`transcript_group_id`:

```python theme={null}
from docent.data_models import Transcript, TranscriptGroup

group = TranscriptGroup(agent_run_id="run-id-123", name="Phase 2")

transcripts = [
    Transcript(
        transcript_group_id=group.id,
        messages=[...],
    ),
]

client.add_transcripts_to_agent_run(
    "my-collection-id",
    "run-id-123",
    transcripts,
    transcript_groups=[group],
)
```

### Parameters

<ParamField body="collection_id" type="str" required>
  ID of the collection containing the agent run.
</ParamField>

<ParamField body="agent_run_id" type="str" required>
  ID of the existing agent run to append to.
</ParamField>

<ParamField body="transcripts" type="list[Transcript]" required>
  Transcripts to add to the agent run. The `id` field must not be explicitly
  set on any transcript — IDs are assigned by the server.
</ParamField>

<ParamField body="transcript_groups" type="list[TranscriptGroup] | None">
  Optional transcript groups to create before inserting the transcripts. Each
  group's `agent_run_id` must match the `agent_run_id` argument. The `id`
  field must not be explicitly set on any group. Any
  `parent_transcript_group_id` and any `transcript_group_id` referenced by the
  new transcripts must point to either one of the supplied groups or an
  existing group in the same agent run.
</ParamField>

<ParamField body="compression" type="Literal[&#x22;gzip&#x22;, &#x22;none&#x22;]" default="gzip">
  Compression algorithm for the request body. Defaults to `gzip`. Set to
  `"none"` to send uncompressed JSON.
</ParamField>

### Returns

<ResponseField name="result" type="dict">
  A dict with the counts of inserted records.

  <Expandable title="Result fields">
    <ResponseField name="transcripts_added" type="int">
      Number of transcripts inserted.
    </ResponseField>

    <ResponseField name="transcript_groups_added" type="int">
      Number of transcript groups inserted.
    </ResponseField>
  </Expandable>
</ResponseField>

### Errors

* **`ValueError`** — A transcript or transcript group has an explicitly set
  `id`; a group's `agent_run_id` does not match the target run; duplicate IDs
  appear in the request; an ID already exists in the database; a referenced
  parent group cannot be found in the same agent run; or the serialized
  payload exceeds 100 MB.
* **`HTTPError (400)`** — Request body is empty or malformed, or the server
  rejected the payload for the reasons above.
* **`HTTPError (404)`** — Agent run not found in the collection.
* **`HTTPError (409)`** — Append conflicted with another concurrent write or
  the agent run was deleted. Retry the request.
* **`HTTPError (415)`** — Unsupported `Content-Encoding`. Only `gzip` and
  `identity` are accepted.

***

## Append Transcript Groups

Convenience wrapper for appending transcript groups without any transcripts.
Equivalent to calling `add_transcripts_to_agent_run` with an empty
`transcripts` list.

```python theme={null}
from docent.data_models import TranscriptGroup

groups = [
    TranscriptGroup(agent_run_id="run-id-123", name="Phase 3"),
]

result = client.add_transcript_groups_to_agent_run(
    collection_id="my-collection-id",
    agent_run_id="run-id-123",
    transcript_groups=groups,
)
print(result)
# {"transcripts_added": 0, "transcript_groups_added": 1}
```

### Parameters

<ParamField body="collection_id" type="str" required>
  ID of the collection containing the agent run.
</ParamField>

<ParamField body="agent_run_id" type="str" required>
  ID of the existing agent run to append to.
</ParamField>

<ParamField body="transcript_groups" type="list[TranscriptGroup]" required>
  Transcript groups to add to the agent run. The `id` field must not be
  explicitly set, and each group's `agent_run_id` must match the
  `agent_run_id` argument.
</ParamField>

<ParamField body="compression" type="Literal[&#x22;gzip&#x22;, &#x22;none&#x22;]" default="gzip">
  Compression algorithm for the request body. Defaults to `gzip`. Set to
  `"none"` to send uncompressed JSON.
</ParamField>

### Returns

<ResponseField name="result" type="dict">
  A dict with `transcripts_added` (always `0`) and `transcript_groups_added`.
</ResponseField>

### Errors

Same as `add_transcripts_to_agent_run`.