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

​
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.