content-agent 0.2.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +38 -0
- package/dist/index.d.ts +500 -52
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +240 -78
- package/dist/index.js.map +1 -1
- package/package.json +9 -6
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { ClientToolDefinition, HeadlessErrorResponse } from "@sanity/agent-types";
|
|
2
|
+
import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3FinishReason, LanguageModelV3GenerateResult, LanguageModelV3StreamPart, LanguageModelV3StreamResult, SharedV3Warning } from "@ai-sdk/provider";
|
|
2
3
|
/**
|
|
3
4
|
* This file was auto-generated by openapi-typescript.
|
|
4
5
|
* Do not make direct changes to the file.
|
|
@@ -399,25 +400,197 @@ interface operations {
|
|
|
399
400
|
};
|
|
400
401
|
};
|
|
401
402
|
}
|
|
403
|
+
/**
|
|
404
|
+
* Request body for the conversation thread endpoint (`POST /{organizationId}/threads/{threadId}`).
|
|
405
|
+
* @category API Types
|
|
406
|
+
*/
|
|
402
407
|
type ChatRequest = components['schemas']['ChatRequest'];
|
|
408
|
+
/**
|
|
409
|
+
* Request body for the one-shot prompt endpoint (`POST /prompt`).
|
|
410
|
+
* @category API Types
|
|
411
|
+
*/
|
|
403
412
|
type GenerateRequest = components['schemas']['PromptRequest'];
|
|
413
|
+
/**
|
|
414
|
+
* Controls how directives in the response are formatted (`'markdown'` or `'directives'`).
|
|
415
|
+
* @category Configuration
|
|
416
|
+
*/
|
|
404
417
|
type OutputFormat = ChatRequest['format'];
|
|
418
|
+
/**
|
|
419
|
+
* Response from the conversation thread endpoint when `stream: false`.
|
|
420
|
+
* @category API Types
|
|
421
|
+
*/
|
|
405
422
|
type ChatResponse = components['schemas']['ChatResponse'];
|
|
423
|
+
/**
|
|
424
|
+
* Error response body returned by the API on failure.
|
|
425
|
+
* @category API Types
|
|
426
|
+
*/
|
|
406
427
|
type ErrorResponse = components['schemas']['ErrorResponse'];
|
|
428
|
+
/**
|
|
429
|
+
* Individual validation issue within an {@link ErrorResponse}.
|
|
430
|
+
* @category API Types
|
|
431
|
+
*/
|
|
407
432
|
type ValidationIssue = components['schemas']['ValidationIssue'];
|
|
433
|
+
/**
|
|
434
|
+
* A message in a conversation (user, assistant, or system).
|
|
435
|
+
* @category API Types
|
|
436
|
+
*/
|
|
408
437
|
type Message = components['schemas']['Message'];
|
|
438
|
+
/**
|
|
439
|
+
* The role of a {@link Message}: `'user'`, `'assistant'`, or `'system'`.
|
|
440
|
+
* @category API Types
|
|
441
|
+
*/
|
|
409
442
|
type MessageRole = Message['role'];
|
|
443
|
+
/**
|
|
444
|
+
* Specifies which Sanity project and dataset the agent should work with.
|
|
445
|
+
*
|
|
446
|
+
* @category Configuration
|
|
447
|
+
*
|
|
448
|
+
* @example
|
|
449
|
+
* ```ts
|
|
450
|
+
* const application = {
|
|
451
|
+
* key: 'project-id.dataset-name',
|
|
452
|
+
* }
|
|
453
|
+
* ```
|
|
454
|
+
*/
|
|
410
455
|
type Application = components['schemas']['Application'];
|
|
456
|
+
/**
|
|
457
|
+
* Resource within an {@link Application}.
|
|
458
|
+
* @category Configuration
|
|
459
|
+
*/
|
|
411
460
|
type ApplicationResource = NonNullable<Application['resource']>;
|
|
461
|
+
/**
|
|
462
|
+
* Agent configuration for controlling behavior, capabilities, and document access.
|
|
463
|
+
*
|
|
464
|
+
* @category Configuration
|
|
465
|
+
*
|
|
466
|
+
* @example Read-only with custom instruction and user message context
|
|
467
|
+
* ```ts
|
|
468
|
+
* const config = {
|
|
469
|
+
* instruction: 'You are a Slack bot helping users manage content.',
|
|
470
|
+
* userMessageContext: {
|
|
471
|
+
* 'slack-channel': '#content-team',
|
|
472
|
+
* 'slack-user': '@john.doe',
|
|
473
|
+
* },
|
|
474
|
+
* capabilities: {
|
|
475
|
+
* read: true,
|
|
476
|
+
* write: false,
|
|
477
|
+
* },
|
|
478
|
+
* }
|
|
479
|
+
* ```
|
|
480
|
+
*
|
|
481
|
+
* @example Read-only document explorer with type filtering
|
|
482
|
+
* ```ts
|
|
483
|
+
* const config = {
|
|
484
|
+
* capabilities: {
|
|
485
|
+
* read: { preset: 'standard' },
|
|
486
|
+
* write: false,
|
|
487
|
+
* },
|
|
488
|
+
* filter: {
|
|
489
|
+
* read: '_type in ["post", "author", "page"]',
|
|
490
|
+
* },
|
|
491
|
+
* }
|
|
492
|
+
* ```
|
|
493
|
+
*/
|
|
412
494
|
type Config = components['schemas']['Config'];
|
|
495
|
+
/**
|
|
496
|
+
* Controls what operations the agent can perform.
|
|
497
|
+
*
|
|
498
|
+
* Each capability (`read`, `write`) can be:
|
|
499
|
+
* - `true` — Full access (standard preset)
|
|
500
|
+
* - `false` — No access
|
|
501
|
+
* - `{ preset: 'minimal' }` — Basic tools only
|
|
502
|
+
* - `{ preset: 'standard' }` — All tools available
|
|
503
|
+
*
|
|
504
|
+
* Use `features` to override individual feature toggles independently of presets.
|
|
505
|
+
*
|
|
506
|
+
* @example Read-only access
|
|
507
|
+
* ```ts
|
|
508
|
+
* const capabilities = { read: true, write: false }
|
|
509
|
+
* ```
|
|
510
|
+
*
|
|
511
|
+
* @example Full read, minimal write
|
|
512
|
+
* ```ts
|
|
513
|
+
* const capabilities = {
|
|
514
|
+
* read: true,
|
|
515
|
+
* write: { preset: 'minimal' },
|
|
516
|
+
* }
|
|
517
|
+
* ```
|
|
518
|
+
*
|
|
519
|
+
* @example Standard read with web search disabled
|
|
520
|
+
* ```ts
|
|
521
|
+
* const capabilities = {
|
|
522
|
+
* read: true,
|
|
523
|
+
* write: false,
|
|
524
|
+
* features: { webSearch: false },
|
|
525
|
+
* }
|
|
526
|
+
* ```
|
|
527
|
+
*
|
|
528
|
+
* @category Configuration
|
|
529
|
+
*/
|
|
413
530
|
type Capabilities = components['schemas']['Capabilities'];
|
|
531
|
+
/**
|
|
532
|
+
* A single capability value: `true`, `false`, or a {@link CapabilityPreset}.
|
|
533
|
+
* @category Configuration
|
|
534
|
+
*/
|
|
414
535
|
type Capability = components['schemas']['Capability'];
|
|
536
|
+
/**
|
|
537
|
+
* A capability preset object, e.g. `{ preset: 'minimal' }` or `{ preset: 'standard' }`.
|
|
538
|
+
* @category Configuration
|
|
539
|
+
*/
|
|
415
540
|
type CapabilityPreset = components['schemas']['CapabilityPreset'];
|
|
541
|
+
/**
|
|
542
|
+
* The preset level string: `'minimal'` or `'standard'`.
|
|
543
|
+
* @category Configuration
|
|
544
|
+
*/
|
|
416
545
|
type CapabilityPresetValue = CapabilityPreset['preset'];
|
|
546
|
+
/**
|
|
547
|
+
* GROQ boolean expressions to control document visibility and mutation permissions.
|
|
548
|
+
*
|
|
549
|
+
* @category Configuration
|
|
550
|
+
*
|
|
551
|
+
* @example
|
|
552
|
+
* ```ts
|
|
553
|
+
* const filter = {
|
|
554
|
+
* read: '_type in ["post", "author", "category"]',
|
|
555
|
+
* write: '_type == "post"',
|
|
556
|
+
* }
|
|
557
|
+
* ```
|
|
558
|
+
*/
|
|
417
559
|
type Filter = components['schemas']['Filter'];
|
|
560
|
+
/**
|
|
561
|
+
* Key-value pairs appended to each user message as XML tags.
|
|
562
|
+
*
|
|
563
|
+
* @category Configuration
|
|
564
|
+
*
|
|
565
|
+
* @example
|
|
566
|
+
* ```ts
|
|
567
|
+
* const userMessageContext = {
|
|
568
|
+
* 'slack-channel': '#marketing',
|
|
569
|
+
* 'user-role': 'editor',
|
|
570
|
+
* }
|
|
571
|
+
* // Renders in the user message as:
|
|
572
|
+
* // <slack-channel>#marketing</slack-channel>
|
|
573
|
+
* // <user-role>editor</user-role>
|
|
574
|
+
* ```
|
|
575
|
+
*/
|
|
418
576
|
type UserMessageContext = NonNullable<Config['userMessageContext']>;
|
|
419
577
|
/**
|
|
420
|
-
* Settings for creating a Content Agent provider instance.
|
|
578
|
+
* Settings for creating a Content Agent provider instance via {@link createContentAgent}.
|
|
579
|
+
*
|
|
580
|
+
* @category Provider
|
|
581
|
+
*
|
|
582
|
+
* @example
|
|
583
|
+
* ```ts
|
|
584
|
+
* import { createContentAgent } from 'content-agent'
|
|
585
|
+
*
|
|
586
|
+
* const contentAgent = createContentAgent({
|
|
587
|
+
* organizationId: 'your-org-id',
|
|
588
|
+
* token: 'your-sanity-token',
|
|
589
|
+
* // Optional overrides:
|
|
590
|
+
* // baseURL: 'https://api.sanity.io',
|
|
591
|
+
* // apiVersion: 'v2026-01-01',
|
|
592
|
+
* })
|
|
593
|
+
* ```
|
|
421
594
|
*/
|
|
422
595
|
interface ContentAgentProviderSettings {
|
|
423
596
|
/**
|
|
@@ -453,6 +626,44 @@ interface ContentAgentProviderSettings {
|
|
|
453
626
|
}
|
|
454
627
|
/**
|
|
455
628
|
* Base settings shared between agent and generate requests.
|
|
629
|
+
*
|
|
630
|
+
* @example Read-only agent with document type filtering
|
|
631
|
+
* ```ts
|
|
632
|
+
* const settings = {
|
|
633
|
+
* application: { key: 'projectId.datasetName' },
|
|
634
|
+
* config: {
|
|
635
|
+
* instruction: 'You are a helpful content assistant for our blog.',
|
|
636
|
+
* capabilities: {
|
|
637
|
+
* read: true,
|
|
638
|
+
* write: false,
|
|
639
|
+
* },
|
|
640
|
+
* filter: {
|
|
641
|
+
* read: '_type in ["post", "author", "category"]',
|
|
642
|
+
* },
|
|
643
|
+
* },
|
|
644
|
+
* }
|
|
645
|
+
* ```
|
|
646
|
+
*
|
|
647
|
+
* @example Read/write agent with perspective locking
|
|
648
|
+
* ```ts
|
|
649
|
+
* const settings = {
|
|
650
|
+
* application: { key: 'projectId.datasetName' },
|
|
651
|
+
* config: {
|
|
652
|
+
* capabilities: {
|
|
653
|
+
* read: true,
|
|
654
|
+
* write: { preset: 'minimal' },
|
|
655
|
+
* },
|
|
656
|
+
* filter: {
|
|
657
|
+
* read: '_type in ["post", "author", "category"]',
|
|
658
|
+
* write: '_type == "post"',
|
|
659
|
+
* },
|
|
660
|
+
* perspectives: {
|
|
661
|
+
* read: ['drafts', 'published'],
|
|
662
|
+
* write: 'drafts',
|
|
663
|
+
* },
|
|
664
|
+
* },
|
|
665
|
+
* }
|
|
666
|
+
* ```
|
|
456
667
|
*/
|
|
457
668
|
interface BaseAgentSettings {
|
|
458
669
|
/**
|
|
@@ -473,10 +684,41 @@ interface BaseAgentSettings {
|
|
|
473
684
|
}
|
|
474
685
|
/**
|
|
475
686
|
* Settings for creating an agent instance (per-thread).
|
|
687
|
+
*
|
|
688
|
+
* Passed as the second argument to {@link ContentAgentProvider.agent | contentAgent.agent(threadId, settings)}.
|
|
689
|
+
*
|
|
690
|
+
* @example
|
|
691
|
+
* ```ts
|
|
692
|
+
* const model = contentAgent.agent('my-thread-id', {
|
|
693
|
+
* application: { key: 'projectId.datasetName' },
|
|
694
|
+
* config: {
|
|
695
|
+
* capabilities: { read: true, write: false },
|
|
696
|
+
* },
|
|
697
|
+
* })
|
|
698
|
+
* ```
|
|
699
|
+
*
|
|
700
|
+
* @category Configuration
|
|
476
701
|
*/
|
|
477
702
|
type AgentSettings = BaseAgentSettings;
|
|
478
703
|
/**
|
|
479
|
-
* Settings for one-shot generation requests.
|
|
704
|
+
* Settings for one-shot generation requests via {@link ContentAgentProvider.prompt | contentAgent.prompt()}.
|
|
705
|
+
*
|
|
706
|
+
* Extends {@link BaseAgentSettings} with an additional `instructions` field
|
|
707
|
+
* for providing custom system-level instructions.
|
|
708
|
+
*
|
|
709
|
+
* @example
|
|
710
|
+
* ```ts
|
|
711
|
+
* const { text } = await contentAgent.prompt(
|
|
712
|
+
* {
|
|
713
|
+
* application: { key: 'projectId.datasetName' },
|
|
714
|
+
* config: { capabilities: { read: true, write: false } },
|
|
715
|
+
* instructions: 'Be concise',
|
|
716
|
+
* },
|
|
717
|
+
* { message: 'List my 5 most recent posts' },
|
|
718
|
+
* )
|
|
719
|
+
* ```
|
|
720
|
+
*
|
|
721
|
+
* @category Configuration
|
|
480
722
|
*/
|
|
481
723
|
interface GenerateSettings extends BaseAgentSettings {
|
|
482
724
|
/**
|
|
@@ -484,6 +726,19 @@ interface GenerateSettings extends BaseAgentSettings {
|
|
|
484
726
|
*/
|
|
485
727
|
instructions?: string;
|
|
486
728
|
}
|
|
729
|
+
/**
|
|
730
|
+
* Options for a one-shot generation request via {@link ContentAgentProvider.prompt | contentAgent.prompt()}.
|
|
731
|
+
*
|
|
732
|
+
* @category Configuration
|
|
733
|
+
*
|
|
734
|
+
* @example
|
|
735
|
+
* ```ts
|
|
736
|
+
* const { text } = await contentAgent.prompt(
|
|
737
|
+
* { instructions: 'Be concise' },
|
|
738
|
+
* { message: 'List all authors in my dataset' },
|
|
739
|
+
* )
|
|
740
|
+
* ```
|
|
741
|
+
*/
|
|
487
742
|
interface GenerateOptions {
|
|
488
743
|
/**
|
|
489
744
|
* The prompt message to send.
|
|
@@ -499,12 +754,20 @@ interface GenerateOptions {
|
|
|
499
754
|
*/
|
|
500
755
|
abortSignal?: AbortSignal;
|
|
501
756
|
}
|
|
757
|
+
/**
|
|
758
|
+
* Result from a one-shot generation request via {@link ContentAgentProvider.prompt | contentAgent.prompt()}.
|
|
759
|
+
*
|
|
760
|
+
* @category Configuration
|
|
761
|
+
*/
|
|
502
762
|
interface GenerateResult {
|
|
503
763
|
/**
|
|
504
764
|
* The generated text response.
|
|
505
765
|
*/
|
|
506
766
|
text: string;
|
|
507
767
|
}
|
|
768
|
+
/**
|
|
769
|
+
* @category Model
|
|
770
|
+
*/
|
|
508
771
|
interface ContentAgentModelConfig {
|
|
509
772
|
provider: string;
|
|
510
773
|
baseURL: string;
|
|
@@ -513,52 +776,117 @@ interface ContentAgentModelConfig {
|
|
|
513
776
|
headers: () => Record<string, string | undefined>;
|
|
514
777
|
fetch?: typeof globalThis.fetch;
|
|
515
778
|
}
|
|
516
|
-
|
|
517
|
-
|
|
779
|
+
/**
|
|
780
|
+
* Vercel AI SDK `LanguageModelV1` implementation that communicates with the
|
|
781
|
+
* Sanity Content Agent API via a conversation thread.
|
|
782
|
+
*
|
|
783
|
+
* Typically you don't construct this directly — use
|
|
784
|
+
* {@link createContentAgent | createContentAgent().agent(threadId)} instead.
|
|
785
|
+
*
|
|
786
|
+
* @category Model
|
|
787
|
+
*
|
|
788
|
+
* @example
|
|
789
|
+
* ```ts
|
|
790
|
+
* import { createContentAgent } from 'content-agent'
|
|
791
|
+
* import { streamText } from 'ai'
|
|
792
|
+
*
|
|
793
|
+
* const contentAgent = createContentAgent({
|
|
794
|
+
* organizationId: 'your-org-id',
|
|
795
|
+
* token: 'your-sanity-token',
|
|
796
|
+
* })
|
|
797
|
+
*
|
|
798
|
+
* const model = contentAgent.agent('my-thread-id', {
|
|
799
|
+
* application: { key: 'projectId.datasetName' },
|
|
800
|
+
* config: {
|
|
801
|
+
* capabilities: { read: true, write: false },
|
|
802
|
+
* },
|
|
803
|
+
* })
|
|
804
|
+
*
|
|
805
|
+
* const { textStream } = await streamText({ model, prompt: 'Summarize my content' })
|
|
806
|
+
* for await (const chunk of textStream) {
|
|
807
|
+
* process.stdout.write(chunk)
|
|
808
|
+
* }
|
|
809
|
+
* ```
|
|
810
|
+
*/
|
|
811
|
+
declare class ContentAgentModel implements LanguageModelV3 {
|
|
812
|
+
readonly specificationVersion: "v3";
|
|
518
813
|
readonly provider: string;
|
|
519
814
|
readonly modelId: string;
|
|
520
|
-
readonly
|
|
815
|
+
readonly supportedUrls: Record<string, RegExp[]>;
|
|
521
816
|
private readonly config;
|
|
522
817
|
private readonly threadId;
|
|
523
818
|
private readonly settings;
|
|
524
819
|
constructor(threadId: string, settings: AgentSettings | undefined, config: ContentAgentModelConfig);
|
|
820
|
+
/**
|
|
821
|
+
* Converts a LanguageModelV3Prompt into wire messages for the agent API.
|
|
822
|
+
*
|
|
823
|
+
* Handles all message roles:
|
|
824
|
+
* - system: plain text system messages
|
|
825
|
+
* - user: extracts text from content parts
|
|
826
|
+
* - assistant: extracts text and/or tool-call parts
|
|
827
|
+
* - tool: converts tool-result parts for the API
|
|
828
|
+
*/
|
|
525
829
|
private convertPromptToMessages;
|
|
830
|
+
/**
|
|
831
|
+
* Extracts client tool definitions from the model call options.
|
|
832
|
+
* Only the schemas are sent — execute functions stay on the client.
|
|
833
|
+
*/
|
|
834
|
+
private extractClientTools;
|
|
526
835
|
private collectWarnings;
|
|
527
836
|
private buildRequestBody;
|
|
528
837
|
private getResponseHeaders;
|
|
529
|
-
doGenerate(options:
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
rawCall: {
|
|
537
|
-
rawPrompt: unknown;
|
|
538
|
-
rawSettings: Record<string, unknown>;
|
|
539
|
-
};
|
|
540
|
-
rawResponse?: {
|
|
541
|
-
headers?: Record<string, string>;
|
|
542
|
-
};
|
|
543
|
-
warnings?: LanguageModelV1CallWarning[];
|
|
544
|
-
}>;
|
|
545
|
-
doStream(options: LanguageModelV1CallOptions): Promise<{
|
|
546
|
-
stream: ReadableStream<LanguageModelV1StreamPart>;
|
|
547
|
-
rawCall: {
|
|
548
|
-
rawPrompt: unknown;
|
|
549
|
-
rawSettings: Record<string, unknown>;
|
|
550
|
-
};
|
|
551
|
-
rawResponse?: {
|
|
552
|
-
headers?: Record<string, string>;
|
|
553
|
-
};
|
|
554
|
-
warnings?: LanguageModelV1CallWarning[];
|
|
555
|
-
}>;
|
|
838
|
+
doGenerate(options: LanguageModelV3CallOptions): Promise<LanguageModelV3GenerateResult>;
|
|
839
|
+
/**
|
|
840
|
+
* Parses a streamed response body into content parts (text and tool calls)
|
|
841
|
+
* and a finish reason. Used by doGenerate to buffer the full response.
|
|
842
|
+
*/
|
|
843
|
+
private extractContentFromStream;
|
|
844
|
+
doStream(options: LanguageModelV3CallOptions): Promise<LanguageModelV3StreamResult>;
|
|
556
845
|
}
|
|
846
|
+
/**
|
|
847
|
+
* A Content Agent provider instance returned by {@link createContentAgent}.
|
|
848
|
+
*
|
|
849
|
+
* Provides two modes of interaction:
|
|
850
|
+
* - **Conversation threads** via {@link ContentAgentProvider.agent | .agent()} — stateful, multi-turn conversations with server-side message history.
|
|
851
|
+
* - **One-shot prompts** via {@link ContentAgentProvider.prompt | .prompt()} — stateless, single-turn interactions.
|
|
852
|
+
*
|
|
853
|
+
* @category Provider
|
|
854
|
+
*/
|
|
557
855
|
interface ContentAgentProvider {
|
|
558
856
|
/**
|
|
559
|
-
* Creates
|
|
857
|
+
* Creates a Vercel AI SDK {@link https://sdk.vercel.ai/docs/ai-sdk-core | LanguageModelV1} for a conversation thread.
|
|
858
|
+
*
|
|
859
|
+
* The thread ID identifies the conversation and maintains message history server-side.
|
|
860
|
+
* If a thread with that ID already exists, the conversation continues. If not, a new
|
|
861
|
+
* thread is automatically created.
|
|
862
|
+
*
|
|
863
|
+
* Use the returned model with `generateText` or `streamText` from the `ai` package.
|
|
864
|
+
*
|
|
865
|
+
* @example
|
|
866
|
+
* ```ts
|
|
867
|
+
* import { generateText, streamText } from 'ai'
|
|
868
|
+
*
|
|
869
|
+
* const model = contentAgent.agent('my-thread-id', {
|
|
870
|
+
* application: { key: 'projectId.datasetName' },
|
|
871
|
+
* config: {
|
|
872
|
+
* capabilities: { read: true, write: false },
|
|
873
|
+
* },
|
|
874
|
+
* })
|
|
875
|
+
*
|
|
876
|
+
* // Non-streaming
|
|
877
|
+
* const { text } = await generateText({ model, prompt: 'What blog posts do I have?' })
|
|
878
|
+
*
|
|
879
|
+
* // Streaming
|
|
880
|
+
* const { textStream } = await streamText({ model, prompt: 'Summarize my content' })
|
|
881
|
+
* for await (const chunk of textStream) {
|
|
882
|
+
* process.stdout.write(chunk)
|
|
883
|
+
* }
|
|
884
|
+
* ```
|
|
885
|
+
*
|
|
886
|
+
* @param threadId - Unique identifier for the conversation thread.
|
|
887
|
+
* @param settings - Optional agent settings (application, capabilities, filters, etc.).
|
|
560
888
|
*/
|
|
561
|
-
agent(threadId: string, settings?: AgentSettings):
|
|
889
|
+
agent(threadId: string, settings?: AgentSettings): LanguageModelV3;
|
|
562
890
|
/**
|
|
563
891
|
* Lists available applications for the organization.
|
|
564
892
|
*
|
|
@@ -579,41 +907,136 @@ interface ContentAgentProvider {
|
|
|
579
907
|
/**
|
|
580
908
|
* Sends a one-shot prompt to the Content Agent (stateless).
|
|
581
909
|
*
|
|
582
|
-
* Unlike
|
|
910
|
+
* Unlike {@link ContentAgentProvider.agent | .agent()}, this does not create or use a conversation thread.
|
|
583
911
|
* Each call is independent with no message history or persistence.
|
|
584
912
|
* Ideal for simple, single-turn interactions.
|
|
585
913
|
*
|
|
586
914
|
* @example
|
|
587
915
|
* ```ts
|
|
588
|
-
* const
|
|
589
|
-
* {
|
|
590
|
-
*
|
|
916
|
+
* const { text } = await contentAgent.prompt(
|
|
917
|
+
* {
|
|
918
|
+
* application: { key: 'projectId.datasetName' },
|
|
919
|
+
* config: { capabilities: { read: true, write: false } },
|
|
920
|
+
* instructions: 'Be concise',
|
|
921
|
+
* },
|
|
922
|
+
* { message: 'List my 5 most recent posts' },
|
|
591
923
|
* )
|
|
592
|
-
* console.log(result.text)
|
|
593
924
|
* ```
|
|
925
|
+
*
|
|
926
|
+
* @param settings - Generation settings (application, capabilities, instructions, etc.).
|
|
927
|
+
* @param options - The prompt message and request options.
|
|
594
928
|
*/
|
|
595
929
|
prompt(settings: GenerateSettings, options: GenerateOptions): Promise<GenerateResult>;
|
|
596
930
|
}
|
|
597
931
|
/**
|
|
598
932
|
* Creates a Content Agent provider instance.
|
|
933
|
+
*
|
|
934
|
+
* The provider is the main entry point for interacting with the Sanity Content Agent API.
|
|
935
|
+
* It returns an object with methods for conversation threads and one-shot prompts.
|
|
936
|
+
*
|
|
937
|
+
* @category Provider
|
|
938
|
+
*
|
|
939
|
+
* @example Basic setup
|
|
940
|
+
* ```ts
|
|
941
|
+
* import { createContentAgent } from 'content-agent'
|
|
942
|
+
*
|
|
943
|
+
* const contentAgent = createContentAgent({
|
|
944
|
+
* organizationId: 'your-org-id',
|
|
945
|
+
* token: 'your-sanity-token',
|
|
946
|
+
* })
|
|
947
|
+
* ```
|
|
948
|
+
*
|
|
949
|
+
* @example Using with Vercel AI SDK for conversation threads
|
|
950
|
+
* ```ts
|
|
951
|
+
* import { createContentAgent } from 'content-agent'
|
|
952
|
+
* import { generateText, streamText } from 'ai'
|
|
953
|
+
*
|
|
954
|
+
* const contentAgent = createContentAgent({
|
|
955
|
+
* organizationId: 'your-org-id',
|
|
956
|
+
* token: 'your-sanity-token',
|
|
957
|
+
* })
|
|
958
|
+
*
|
|
959
|
+
* const model = contentAgent.agent('my-thread-id', {
|
|
960
|
+
* application: { key: 'projectId.datasetName' },
|
|
961
|
+
* config: {
|
|
962
|
+
* capabilities: { read: true, write: false },
|
|
963
|
+
* },
|
|
964
|
+
* })
|
|
965
|
+
*
|
|
966
|
+
* // Non-streaming
|
|
967
|
+
* const { text } = await generateText({ model, prompt: 'What blog posts do I have?' })
|
|
968
|
+
*
|
|
969
|
+
* // Streaming
|
|
970
|
+
* const { textStream } = await streamText({ model, prompt: 'Summarize my content' })
|
|
971
|
+
* for await (const chunk of textStream) {
|
|
972
|
+
* process.stdout.write(chunk)
|
|
973
|
+
* }
|
|
974
|
+
* ```
|
|
975
|
+
*
|
|
976
|
+
* @example One-shot generation (stateless, no thread)
|
|
977
|
+
* ```ts
|
|
978
|
+
* const { text } = await contentAgent.prompt(
|
|
979
|
+
* {
|
|
980
|
+
* application: { key: 'projectId.datasetName' },
|
|
981
|
+
* config: { capabilities: { read: true, write: false } },
|
|
982
|
+
* instructions: 'Be concise',
|
|
983
|
+
* },
|
|
984
|
+
* { message: 'List my 5 most recent posts' },
|
|
985
|
+
* )
|
|
986
|
+
* ```
|
|
987
|
+
*
|
|
988
|
+
* @param options - Provider configuration including organization ID, token, and optional overrides.
|
|
599
989
|
*/
|
|
600
990
|
declare function createContentAgent(options: ContentAgentProviderSettings): ContentAgentProvider;
|
|
601
991
|
/**
|
|
602
992
|
* Builds headers for API requests, filtering out undefined values.
|
|
993
|
+
*
|
|
994
|
+
* @category Utilities
|
|
603
995
|
*/
|
|
604
996
|
declare function buildHeaders(configHeaders: Record<string, string | undefined>, additionalHeaders?: Record<string, string>): Record<string, string>;
|
|
605
997
|
/**
|
|
606
998
|
* Constructs the full API URL for an endpoint.
|
|
999
|
+
*
|
|
1000
|
+
* @category Utilities
|
|
607
1001
|
*/
|
|
608
1002
|
declare function buildApiUrl(baseURL: string, apiVersion: string, endpoint: string): string;
|
|
609
1003
|
/**
|
|
610
1004
|
* Custom error class for Sanity Agent API errors.
|
|
1005
|
+
* The {@link body} is parsed from the JSON response and follows the
|
|
1006
|
+
* {@link HeadlessErrorResponse} shape defined in `@sanity/agent-types`.
|
|
1007
|
+
*
|
|
1008
|
+
* @category Utilities
|
|
611
1009
|
*/
|
|
612
1010
|
declare class SanityAgentError extends Error {
|
|
613
1011
|
readonly status: number;
|
|
614
1012
|
readonly isRetryable: boolean;
|
|
1013
|
+
readonly body: Partial<HeadlessErrorResponse>;
|
|
615
1014
|
constructor(status: number, message: string);
|
|
1015
|
+
private static parseBody;
|
|
616
1016
|
}
|
|
1017
|
+
declare const GENERIC_ERROR_MESSAGE = "Sorry, something went wrong. Please try again.";
|
|
1018
|
+
type AgentErrorType = {
|
|
1019
|
+
type: 'no_applications';
|
|
1020
|
+
} | {
|
|
1021
|
+
type: 'application_not_found';
|
|
1022
|
+
} | {
|
|
1023
|
+
type: 'unknown';
|
|
1024
|
+
};
|
|
1025
|
+
/**
|
|
1026
|
+
* Classifies a caught error from the Content Agent API into a known error type.
|
|
1027
|
+
* Useful for clients that need to take different actions per error (e.g. show
|
|
1028
|
+
* resource-selection buttons). For the user-facing message, use {@link getAgentErrorMessage}.
|
|
1029
|
+
*
|
|
1030
|
+
* @category Utilities
|
|
1031
|
+
*/
|
|
1032
|
+
declare function classifyAgentError(error: unknown): AgentErrorType;
|
|
1033
|
+
/**
|
|
1034
|
+
* Extracts a user-facing error message from an agent API error.
|
|
1035
|
+
* Returns the message sent by the API when available, otherwise a generic fallback.
|
|
1036
|
+
*
|
|
1037
|
+
* @category Utilities
|
|
1038
|
+
*/
|
|
1039
|
+
declare function getAgentErrorMessage(error: unknown): string;
|
|
617
1040
|
interface FetchOptions {
|
|
618
1041
|
url: string;
|
|
619
1042
|
body: unknown;
|
|
@@ -624,37 +1047,62 @@ interface FetchOptions {
|
|
|
624
1047
|
/**
|
|
625
1048
|
* Makes a POST request and returns the response.
|
|
626
1049
|
* Throws SanityAgentError if the response is not ok.
|
|
1050
|
+
*
|
|
1051
|
+
* @category Utilities
|
|
627
1052
|
*/
|
|
628
1053
|
declare function fetchApi(options: FetchOptions): Promise<Response>;
|
|
629
1054
|
/**
|
|
630
1055
|
* Extracts text content from message parts (user or assistant).
|
|
1056
|
+
*
|
|
1057
|
+
* @category Utilities
|
|
631
1058
|
*/
|
|
632
1059
|
declare function extractTextFromParts(content: string | Array<{
|
|
633
1060
|
type: string;
|
|
634
1061
|
text?: string;
|
|
635
1062
|
}>): string;
|
|
636
1063
|
/**
|
|
637
|
-
* Maps API finish reasons to
|
|
1064
|
+
* Maps API finish reasons to LanguageModelV3FinishReason.
|
|
1065
|
+
*
|
|
1066
|
+
* @category Utilities
|
|
638
1067
|
*/
|
|
639
|
-
declare function mapFinishReason(reason: string | undefined):
|
|
1068
|
+
declare function mapFinishReason(reason: string | undefined): LanguageModelV3FinishReason;
|
|
1069
|
+
type ParsedStreamLine = {
|
|
1070
|
+
kind: 'part';
|
|
1071
|
+
part: LanguageModelV3StreamPart;
|
|
1072
|
+
} | {
|
|
1073
|
+
kind: 'finish';
|
|
1074
|
+
finishReason: LanguageModelV3FinishReason;
|
|
1075
|
+
};
|
|
640
1076
|
/**
|
|
641
|
-
* Parses a single line from Vercel AI Data Stream Protocol.
|
|
1077
|
+
* Parses a single line from the Vercel AI Data Stream Protocol.
|
|
642
1078
|
* Returns null if the line cannot be parsed or should be ignored.
|
|
1079
|
+
*
|
|
1080
|
+
* Protocol prefixes:
|
|
1081
|
+
* 0:"text" – text content
|
|
1082
|
+
* 2:[data] – data array (ignored)
|
|
1083
|
+
* 3:"error" – error
|
|
1084
|
+
* b:{toolCallId,toolName,args} – client tool call
|
|
1085
|
+
* d:{finishReason, usage} – finish message
|
|
1086
|
+
* e:{finishReason, usage} – finish step
|
|
1087
|
+
*
|
|
1088
|
+
* @see https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol
|
|
1089
|
+
*
|
|
1090
|
+
* @category Utilities
|
|
643
1091
|
*/
|
|
644
|
-
declare function parseStreamLine(line: string):
|
|
645
|
-
/**
|
|
646
|
-
* Parses finish metadata from a stream line.
|
|
647
|
-
* Returns the finish reason if found, null otherwise.
|
|
648
|
-
*/
|
|
649
|
-
declare function parseFinishLine(line: string): LanguageModelV1FinishReason | null;
|
|
1092
|
+
declare function parseStreamLine(line: string, textContentId: string): ParsedStreamLine | null;
|
|
650
1093
|
/**
|
|
651
1094
|
* Extracts accumulated text from a streaming response body.
|
|
652
1095
|
* Used for simple streaming cases where only the final text is needed.
|
|
1096
|
+
*
|
|
1097
|
+
* @category Utilities
|
|
653
1098
|
*/
|
|
654
1099
|
declare function extractTextFromStream(responseBody: ReadableStream<Uint8Array>): Promise<string>;
|
|
655
1100
|
/**
|
|
656
|
-
* Creates a ReadableStream that parses SSE data from a response body
|
|
1101
|
+
* Creates a ReadableStream that parses SSE data from a response body
|
|
1102
|
+
* and emits LanguageModelV3 stream parts with proper lifecycle events.
|
|
1103
|
+
*
|
|
1104
|
+
* @category Utilities
|
|
657
1105
|
*/
|
|
658
|
-
declare function createSSEStream(responseBody: ReadableStream<Uint8Array
|
|
659
|
-
export { type AgentSettings, type Application, type ApplicationResource, type Capabilities, type Capability, type CapabilityPreset, type CapabilityPresetValue, type ChatRequest, type ChatResponse, type Config, ContentAgentModel, type ContentAgentModelConfig, type ContentAgentProvider, type ContentAgentProviderSettings, type ErrorResponse, type Filter, type GenerateOptions, type GenerateRequest, type GenerateResult, type GenerateSettings, type Message, type MessageRole, type OutputFormat, SanityAgentError, type UserMessageContext, type ValidationIssue, buildApiUrl, buildHeaders, type components, createContentAgent, createSSEStream, extractTextFromParts, extractTextFromStream, fetchApi, mapFinishReason, type operations,
|
|
1106
|
+
declare function createSSEStream(responseBody: ReadableStream<Uint8Array>, warnings: SharedV3Warning[]): ReadableStream<LanguageModelV3StreamPart>;
|
|
1107
|
+
export { type AgentErrorType, type AgentSettings, type Application, type ApplicationResource, type Capabilities, type Capability, type CapabilityPreset, type CapabilityPresetValue, type ChatRequest, type ChatResponse, type ClientToolDefinition, type Config, ContentAgentModel, type ContentAgentModelConfig, type ContentAgentProvider, type ContentAgentProviderSettings, type ErrorResponse, type Filter, GENERIC_ERROR_MESSAGE, type GenerateOptions, type GenerateRequest, type GenerateResult, type GenerateSettings, type Message, type MessageRole, type OutputFormat, type ParsedStreamLine, SanityAgentError, type UserMessageContext, type ValidationIssue, buildApiUrl, buildHeaders, classifyAgentError, type components, createContentAgent, createSSEStream, extractTextFromParts, extractTextFromStream, fetchApi, getAgentErrorMessage, mapFinishReason, type operations, parseStreamLine, type paths };
|
|
660
1108
|
//# sourceMappingURL=index.d.ts.map
|