Function useAgentPrompt

useAgentPrompt(
resourceHandle?: ResourceHandle<string, string>,
): (options: PromptRequest) => Promise<string>

Alpha

Prompts the Content Agent using the same instruction template format as other agent actions.

Parameters

OptionalresourceHandle: ResourceHandle<string, string>

Returns (options: PromptRequest) => Promise<string>

A stable callback that triggers the action and resolves a Promise with the prompt result.

Remarks

This hook provides a stable callback to send prompts to the Content Agent and receive responses. Unlike the other agent action hooks, this one does not modify documents—it simply returns the AI's response.

Features:

Uses the same instruction template format with $variables as other actions.
format: 'string' or 'json' (instruction must contain the word "json" for JSON responses).
Supports instructionParams for dynamic content (constants, fields, documents, GROQ queries).
Optional temperature for controlling response creativity.

Example: Basic string prompt

import {useState} from 'react'
import {useAgentPrompt} from '@sanity/sdk-react'

function AskQuestion() {
  const prompt = useAgentPrompt()
  const [answer, setAnswer] = useState<string>('')

  const handleAsk = async () => {
    const result = await prompt({
      instruction: 'What are the top 3 benefits of content modeling?',
      format: 'string',
    })
    setAnswer(result.output)
  }

  return (
    <div>
      <button onClick={handleAsk}>Ask AI</button>
      {answer && <p>{answer}</p>}
    </div>
  )
}

Example: JSON response with instruction params

import {useState} from 'react'
import {useAgentPrompt} from '@sanity/sdk-react'

interface TagSuggestions {
  tags: string[]
  reasoning: string
}

function SuggestTags({documentId}: {documentId: string}) {
  const prompt = useAgentPrompt()
  const [suggestions, setSuggestions] = useState<TagSuggestions | null>(null)

  const handleSuggest = async () => {
    const result = await prompt({
      instruction: `
        Based on the following article title and content, suggest relevant tags.
        Return as json with "tags" (array of strings) and "reasoning" (string).
        Title: $title
        Content: $body
      `,
      instructionParams: {
        title: {type: 'field', path: 'title', documentId},
        body: {type: 'field', path: 'body', documentId},
      },
      format: 'json',
    })
    setSuggestions(result.output as TagSuggestions)
  }

  return (
    <div>
      <button onClick={handleSuggest}>Suggest Tags</button>
      {suggestions && (
        <div>
          <p>Reasoning: {suggestions.reasoning}</p>
          <ul>
            {suggestions.tags.map((tag) => (
              <li key={tag}>{tag}</li>
            ))}
          </ul>
        </div>
      )}
    </div>
  )
}