Creating instructions
How instructions and style guides shape what Agent Actions produce, and how to pass data into them with parameters.
Instructions tell Agent Actions how to manipulate your data. Some actions, like Generate, rely almost entirely on your instructions and your schema. Others, like Translate, use instructions to further refine their default behavior. If you've used other AI tools, instructions are like prompts.
There are two types of instructions:
instruction: Used by Generate, Transform, and Prompt. This pairs with theinstructionParamsoption to pass data into the instruction.styleGuide: Used by Translate. This pairs with thestyleGuideParamsoption to pass data into the instruction.
Aside from the difference in syntax, the concepts are the same for both instruction and styleGuide.
Sanity client
The code examples on this page use client to refer to a configured @sanity/client. For details on configuring the client, refer to the client documentation or one of the Agent Actions guides, like the Generate quick start.
Basic instructions
At their most basic, instructions are a string telling the Agent Action what you want it to do:
await client.agent.action.generate({
// Replace with your schema ID
schemaId: "YOUR_SCHEMA_ID",
// Tell the client to create a new 'movie' document type.
targetDocument: { operation: "create", _type: "movie" },
// Provide an instruction, or prompt.
instruction: "Create a movie about cats.",
});await client.agent.action.transform({
// Replace with your schema ID
schemaId: "YOUR_SCHEMA_ID",
// Tell the client the ID of the document to transform.
documentId: "YOUR_DOCUMENT_ID",
// Provide an instruction, or prompt.
instruction: "Change all instances of 'Alien' to 'Lifeform from another planet'. Match the case of the existing text.",
});await client.agent.action.translate({
// Replace with your schema ID
schemaId: "YOUR_SCHEMA_ID",
// Tell the client the ID of the document to use as the source.
documentId: "YOUR_DOCUMENT_ID",
// Set the operation mode
targetDocument: { operation: "create" },
// Set the 'from' and 'to' language
fromLanguage: {id: "en-US", title: "English"},
toLanguage: {id: "el-GR", title: "Greek"},
// Use `styleGuide` instead of instruction for Translate
styleGuide: "Use a formal tone when translating.",
});Instruction parameters
You can provide additional information to the instructions by defining and passing instructionParams (and styleGuideParams for Translate).
Here's an example that uses a basic constant value:
await client.agent.action.generate({
// Replace with your schema ID
schemaId: "YOUR_SCHEMA_ID",
// Tell the client to create a new 'movie' document type.
targetDocument: { operation: "create", _type: "movie" },
// Provide an instruction, or prompt.
instruction: "Create a movie about $topic.",
instructionParams: {
topic: 'cats'
}
});await client.agent.action.transform({
// Replace with your schema ID
schemaId: "YOUR_SCHEMA_ID",
// Tell the client the ID of the document to transform.
documentId: "YOUR_DOCUMENT_ID",
// Provide an instruction, or prompt.
instruction: "Change all instances of '$old' to '$new'. Match the case of the existing text.",
instructionParams: {
old: 'Alien',
new: 'Lifeform from another planet'
}
});await client.agent.action.translate({
// Replace with your schema ID
schemaId: "YOUR_SCHEMA_ID",
// Tell the client the ID of the document to use as the source.
documentId: "YOUR_DOCUMENT_ID",
// Set the operation mode
targetDocument: { operation: "create" },
// Set the 'from' and 'to' language
fromLanguage: {id: "en-US", title: "English"},
toLanguage: {id: "el-GR", title: "Greek"},
// Use `styleGuide` instead of instruction for Translate
styleGuide: "Use a $tone tone when translating.",
styleGuideParams: {
tone: 'formal'
}
});There are two essential things to note about this example:
- The parameter names (
topic,old,new, andtone) can be any variable name. - The parameter name is passed into the instruction by prepending
$.
This example uses a constant value, but there are multiple types of parameters.
Constant parameters
The constant parameter type sets a fixed value. Its shorthand form assigns the value directly; here's the full version:
await client.agent.action.generate({
// ...
instruction: "Write the details for a movie about $topic",
instructionParams: {
topic: {
type: "constant",
value: "cats"
}
}
})await client.agent.action.translate({
// ...
styleGuide: "Use a $tone tone when translating.",
styleGuideParams: {
tone: {
type: "constant",
value: "formal"
}
}
});Field parameters
The field parameter type picks the value from a field in the source document (if one exists), then passes that to the instruction with the $-prefixed parameter syntax.
You can also provide an optional documentId along with the field path to pick a value from any document in your dataset. If you omit it, the action uses the source document set by the top-level documentId, or the ID given in an edit operation:
await client.agent.action.generate({
// ...
instruction: "Write the details for a movie about $topic",
instructionParams: {
topic: {
type: "field",
path: "movie_idea",
documentId: "YOUR_DOCUMENT_ID" // Optional. Defaults to the source document.
}
}
})await client.agent.action.translate({
// ...
styleGuide: "Use a $tone tone when translating.",
styleGuideParams: {
tone: {
type: "field",
path: "formality",
documentId: "YOUR_DOCUMENT_ID" // optional
}
}
});The path should be a full path to the field in the document. For examples of paths, see the common patterns guide.
Document parameters
The document parameter type sets the parameter to the full contents of a document. For larger documents, this might become too large and cause issues with the accuracy of the instruction:
await client.agent.action.generate({
// ...
instruction: "Develop a new movie. Use these details to generate the concept: $background",
instructionParams: {
background: {
type: "document",
documentId: "YOUR_DOCUMENT_ID"
}
}
})await client.agent.action.translate({
// ...
styleGuide: "Use the following company guidelines when translating: $guidelines",
styleGuideParams: {
guidelines: {
type: "document",
documentId: "YOUR_DOCUMENT_ID"
}
}
});This can be useful for passing in singleton-style documents, or using existing documents as background context.
GROQ parameters
If field and document aren't powerful enough, you can also write GROQ queries to populate the contents of your instruction parameters:
await client.agent.action.generate({
// ...
instruction: "Develop a new movie. Use these details to generate the concept: $background",
instructionParams: {
background: {
type: "groq",
query: "*[_id == $id][0]",
perspective: "drafts",
params: {
id: "YOUR_DOCUMENT_ID"
}
}
}
})await client.agent.action.translate({
// ...
styleGuide: "Use the following company guidelines when translating: $guidelines",
styleGuideParams: {
guidelines: {
type: "groq",
query: "*[_id == $id][0]",
perspective: "drafts",
params: {
id: "YOUR_DOCUMENT_ID"
}
}
}
});GROQ queries accept filters, projections, perspective, and can receive their own parameters as seen in the example. The perspective option only accepts a single perspective.
Multiple parameters
An instruction can take more than one parameter, and you can mix any combination of parameter types to build it:
await client.agent.action.generate({
schemaId: "YOUR_SCHEMA_ID",
targetDocument: { operation: "create", _type: "movie" },
instruction: "Create a movie with the title: $title. Use the following details to come up with a synopsis and characters: $backgroundDetails",
instructionParams: {
title: {
type: "constant",
value: "Sanity: The Content Operating System"
},
backgroundDetails: {
type: "document",
documentId: "YOUR_DOCUMENT_ID"
}
},
});Per-path instructions
Some Agent Actions support per-path instructions. For example, you can provide a top-level instruction for all fields, and then specific instructions for individual fields. Learn more about this approach in the targets and paths documentation.
Instruction size limits
The instruction and instructionParams settings are only part of what Agent Actions use when creating content. They also know about your schema and any document used as the source.
The instruction for Transform and the styleGuide for Translate are capped at 2,000 characters, measured after instructionParams and styleGuideParams have been interpolated. As instructions get larger, they can also exceed the maximum size accepted by the large language model. If you're experiencing inconsistent or unexpected results, try reducing the information you pass to the instructions.