Append to Agent Runs

Use these methods to extend an existing agent run with additional transcripts 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

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:

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

collection_id

str

required

ID of the collection containing the agent run.

agent_run_id

str

required

ID of the existing agent run to append to.

transcripts

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.

transcript_groups

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.

compression

Literal["gzip", "none"]

default:"gzip"

Compression algorithm for the request body. Defaults to gzip. Set to "none" to send uncompressed JSON.

Returns

result

dict

A dict with the counts of inserted records.

Show Result fields

transcripts_added

int

Number of transcripts inserted.

transcript_groups_added

int

Number of transcript groups inserted.

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.

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

collection_id

str

required

ID of the collection containing the agent run.

agent_run_id

str

required

ID of the existing agent run to append to.

transcript_groups

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.

compression

Literal["gzip", "none"]

default:"gzip"

Compression algorithm for the request body. Defaults to gzip. Set to "none" to send uncompressed JSON.

Returns

result

dict

A dict with transcripts_added (always 0) and transcript_groups_added.

Errors

Same as add_transcripts_to_agent_run.

Getting Started

Collections

Agent Runs

DQL

Feedback & Labels

More

Legacy

Append to Agent Runs

Append Transcripts

Parameters

Returns

Errors

Append Transcript Groups

Parameters

Returns

Errors

​Append Transcripts

​Parameters

​Returns

​Errors

​Append Transcript Groups

​Parameters

​Returns

​Errors

Append Transcripts

Parameters

Returns

Errors

Append Transcript Groups

Parameters

Returns

Errors