Circle V2 API Docs
    Preparing search index...

    Answers ONE form field from the patient's chart, with citations it must be able to quote.

    One field per loop rather than v1's batch: a batch shares its retrieval across fields that want different evidence (v1 concatenated the parent prompt and every sub-prompt into a single query), and one field's failure takes the batch with it. Per-field also gives the runner something to bound — concurrency, a timeout, and a partial result the caller can persist as it lands.

    Hierarchy

    Index

    Constructors

    • Parameters

      • config: {
            settings: {
                citationSimilarityThreshold: number;
                confidenceThreshold: number;
                enableCitationValidation: boolean;
                enableConfidenceGate: boolean;
                enableExclusiveChoiceModeling: boolean;
                evidenceCharBudget: number;
                fieldConcurrency: number;
                fieldTimeoutMs: number;
                maxCitationsPerField: number;
                promptCacheKeyBuckets: number;
                recursionLimit: number;
                requireCitationForFilled: boolean;
                requireRetrievalBeforeAnswer: boolean;
                retryWhenOverBudget: boolean;
                setupTimeoutMs: number;
            };
            tools: { enableListFormFields: boolean; enableSearchChart: boolean };
        }
        • settings: {
              citationSimilarityThreshold: number;
              confidenceThreshold: number;
              enableCitationValidation: boolean;
              enableConfidenceGate: boolean;
              enableExclusiveChoiceModeling: boolean;
              evidenceCharBudget: number;
              fieldConcurrency: number;
              fieldTimeoutMs: number;
              maxCitationsPerField: number;
              promptCacheKeyBuckets: number;
              recursionLimit: number;
              requireCitationForFilled: boolean;
              requireRetrievalBeforeAnswer: boolean;
              retryWhenOverBudget: boolean;
              setupTimeoutMs: number;
          }
          • citationSimilarityThreshold: number

            Similarity bar for a quote that fails the exact-substring check. At 1 only an exact normalized match counts; below it a lightly reworded or re-punctuated quote can still verify.

          • confidenceThreshold: number

            Below this self-rated confidence an answered field is downgraded to no_answer.

          • enableCitationValidation: boolean

            Verify every cited quote is present in what the agent was actually shown before the answer ships; unverifiable citations are dropped. Off only in tests that stub the transcript.

          • enableConfidenceGate: boolean

            Whether confidenceThreshold is enforced at all.

          • enableExclusiveChoiceModeling: boolean

            Model a checkbox group carrying v1's exclusivity sentence as a single one-of choice, and strip that sentence from the question shown to the model. When off, the group is answered as independent sub-fields and only the post-hoc exactly-one check applies.

          • evidenceCharBudget: number

            Character budget for the evidence corpus retained per field from the tool transcript — the text citations are proven against. It bounds VERIFICATION memory/CPU, not the prompt, so it is set well above a long chart export: a document that overruns it is truncated (not dropped), but a citation quoting past the cut would still fail to verify.

          • fieldConcurrency: number

            How many fields are answered at once. v1 ran an uncapped Promise.all over every annotation, so a 60-field form opened 60 concurrent model loops and rate-limited itself.

          • fieldTimeoutMs: number

            Wall-clock bound on ONE field, after which it resolves as error and the run continues. A stuck field must not take the other 59 down with it.

          • maxCitationsPerField: number

            Upper bound on citations kept per field. Beyond this the extras are noise, not provenance.

          • promptCacheKeyBuckets: number

            How many promptCacheKey buckets to spread over; 1 is shipped behaviour. See promptCacheKey.ts.

          • recursionLimit: number

            Super-steps per field (a lookup costs two, the answer one). 32 is the most fieldTimeoutMs affords across both guard passes.

          • requireCitationForFilled: boolean

            Downgrade an answered field with no surviving citation to no_answer. This is the hallucination control: a value with nothing behind it is exactly the wrong thing to write onto a form nobody re-reads.

          • requireRetrievalBeforeAnswer: boolean

            Refuse a first pass that made no chart tool call and re-ask once, inside the same fieldTimeoutMs.

          • retryWhenOverBudget: boolean

            Re-ask once, with its own fieldTimeoutMs, when a text answer runs past its box's character budget; the shorter answer replaces it only if it fits, else the first answer stands and is flagged.

          • setupTimeoutMs: number

            Wall-clock bound on the run's SETUP — patient context plus vector stores — before any field runs.

        • tools: { enableListFormFields: boolean; enableSearchChart: boolean }

          Toolset selection. fetch_document is always on — it is how the agent reads anything.

          • enableListFormFields: boolean

            Include list_form_fields, so the agent can see the neighbouring fields of the form it is filling. Costs a turn; pays for itself when a field's meaning depends on its siblings.

          • enableSearchChart: boolean

            Include search_chart (semantic retrieval across the run's selected documents + EMR).

      • Optionaloptions: { modelOverride?: PromptModelConfig; promptCacheSeed?: string }

      Returns FormFillingAgent

    Properties

    modelOverride?: PromptModelConfig
    outputSchema: ZodObject<
        {
            checkboxValue: ZodNullable<
                ZodEnum<
                    { checked: "checked"; unchecked: "unchecked"; unknown: "unknown" },
                >,
            >;
            citations: ZodArray<
                ZodObject<
                    {
                        documentId: ZodNullable<ZodString>;
                        documentType: ZodNullable<ZodString>;
                        name: ZodNullable<ZodString>;
                        page: ZodNullable<ZodNumber>;
                        quote: ZodString;
                    },
                    $strict,
                >,
            >;
            confidence: ZodNumber;
            listValues: ZodNullable<ZodArray<ZodString>>;
            outcome: ZodEnum<{ answered: "answered"; not_found: "not_found" }>;
            selectedOption: ZodNullable<ZodString>;
            subFieldValues: ZodArray<
                ZodObject<{ name: ZodString; value: ZodNullable<ZodString> }, $strict>,
            >;
            textValue: ZodNullable<ZodString>;
        },
        $strict,
    > = agentFormFieldAnswerSchema

    Structured shape the loop must return. Typed as LangChain's interop schema so createAgent's overload infers T = TOutput directly (no cast). Subclasses still declare it with z.object(...), which is assignable to InteropZodType<TOutput>.

    recursionLimit: number = DEFAULT_RECURSION_LIMIT

    Bounds the tool loop. Override to widen/narrow.

    snapshot: {
        description: string;
        inputVariables: string[];
        model: { model: string; temperature: number };
        name: string;
        tags: string[];
        template: string;
        templateFormat: string;
    } = snapshot

    Committed cold-start snapshot for the system prompt (hub name, template, model).

    Accessors

    • get agentName(): string

      Hub identifier — derived from the committed snapshot.

      Returns string

    Methods

    • The seed messages for the loop. Defaults to a single user turn.

      Parameters

      Returns BaseMessageLike[]

    • Build the ChatOpenAI instance from the already-resolved config — resolveSystemPrompt has applied any override by this point. Tests override this to inject a fake.

      Parameters

      Returns ChatOpenAI

    • The answer is a tool the model must pick over search_chart: with the bare schema LangChain sends response_format on every request, and a temperature-0 model answers not_found on turn one.

      Returns AgentResponseFormat<
          {
              checkboxValue: "unknown"
              | "checked"
              | "unchecked"
              | null;
              citations: {
                  documentId: string | null;
                  documentType: string | null;
                  name: string | null;
                  page: number | null;
                  quote: string;
              }[];
              confidence: number;
              listValues: string[]
              | null;
              outcome: "not_found" | "answered";
              selectedOption: string | null;
              subFieldValues: { name: string; value: string | null }[];
              textValue: string | null;
          },
      >

    • The tools the agent may call. May be empty. Optional runner ctx threads into .toTool(ctx).

      Parameters

      Returns (ServerTool | ClientTool)[]

    • The seed user turn for the loop. Override buildMessages for full control.

      Parameters

      Returns string

    • Parameters

      Returns Promise<
          AgentResult<
              {
                  checkboxValue: "unknown"
                  | "checked"
                  | "unchecked"
                  | null;
                  citations: {
                      documentId: string | null;
                      documentType: string | null;
                      name: string | null;
                      page: number | null;
                      quote: string;
                  }[];
                  confidence: number;
                  listValues: string[]
                  | null;
                  outcome: "not_found" | "answered";
                  selectedOption: string | null;
                  subFieldValues: { name: string; value: string | null }[];
                  textValue: string | null;
              },
          >,
      >

    • Defaults to the agent's snapshot name — each has a distinct static prefix, so same-prefix traffic routes together and realizes the automatic cache at volume. Override to spread one agent's traffic over several keys.

      Returns string

    • Optional verbatim system prompt. When it returns a non-empty string, the agent uses it as-is, bypassing the hub and variable formatting. Defaults to none.

      Parameters

      Returns string | undefined

    • Pure: map typed input to the system-prompt template's variables.

      Parameters

      Returns Record<string, unknown>

    • Optional non-PII trace inputs for the child span.

      Parameters

      Returns Record<string, unknown>