Documentation
¶
Overview ¶
Package agentinstructions owns the policy that applies to an agent's instruction text whichever layer it belongs to and whichever writer produced it: the byte bound and size advisory on the deployment's customized layer (server.agent_instructions), the store that layer is read and written through, and the index-entry form both layers point at a knowledge page with.
The customized layer is the deployment's own half of what a session reads, composed beneath the platform's built-in baseline by pkg/platform/instructions.ComposeForCaller and carried in the first response of every session. Two writers produce it -- the apply_knowledge agent_instructions sink and PUT /admin/config/entries/server.agent_instructions -- so the policy lives here rather than in either of them.
Index ¶
Constants ¶
const ( // MaxCustomizedBytes refuses a write past roughly eight thousand tokens of // instruction text. It is a ceiling on runaway growth, not a target: a // deployment writing a document this size is carrying a knowledge base in a // field composed into every session. MaxCustomizedBytes = 32 << 10 // AdviseCustomizedBytes is where a write still succeeds but says the layer // is getting long. It sits at roughly three thousand tokens, above what a // short set of hard operating rules needs, so the advisory arrives while // compaction is still cheap. AdviseCustomizedBytes = 12 << 10 )
Byte bounds on the customized instruction layer -- the deployment's own server.agent_instructions, the second of the two layers ComposeForCaller joins. The layer is composed into the first response of every session on the deployment, so its size is paid for by every caller before any work happens, and nothing else bounds it: the column is unbounded TEXT and neither the config store nor its REST writer measured a value before #1607.
The bound belongs to the layer rather than to whichever writer produced it, so both writers enforce it: the apply_knowledge agent_instructions sink and PUT /api/v1/admin/config/entries/server.agent_instructions.
const KnowledgePageAlternative = "move the longer guidance to a knowledge page and index it " +
"from the instructions as mcp:knowledge_page:<slug>"
KnowledgePageAlternative is what an over-limit write is told to do instead: the sentence is here so the refusal, the advisory, and the editor's banner name one remedy rather than three phrasings of it.
Variables ¶
This section is empty.
Functions ¶
func CheckCustomizedSize ¶
CheckCustomizedSize returns an *OversizeError when value exceeds MaxCustomizedBytes, and nil otherwise. Both writers of the customized layer call it before the write, so an over-limit value is refused rather than stored and paid for by every later session.
func CustomizedNotice ¶
CustomizedNotice returns the soft advisory for a customized layer that has grown past AdviseCustomizedBytes, or "" when it has not. The write it describes has already succeeded: this is the signal that the layer is drifting from a set of rules toward a document, in time to compact it rather than after a refusal.
func IndexEntry ¶
IndexEntry renders one line of a page index in an agent's instructions: the page's reference followed by what reading it answers.
Both instruction layers render this line -- the platform baseline's index of its shipped guidance (pkg/platform/instructions.pageIndex) and the customized layer's entry left behind by a promotion too long to stay a rule (#1607). One renderer serves both, so a reader is never handed two shapes for one thing.
func KnowledgePageRef ¶
KnowledgePageRef is the reference form `fetch` resolves a knowledge page by. A built-in page's row id is generated per deployment at reconcile time, so a slug is the only handle written guidance can name (#1476).
Types ¶
type Layer ¶
type Layer struct {
// contains filtered or unexported fields
}
Layer adapts the platform's config plumbing onto the knowledge toolkit's InstructionsStore: the customized agent-instruction layer read as the value every session sees, and written as the database override that value resolves from.
func (Layer) AgentInstructions ¶
AgentInstructions returns the effective customized instruction text: the stored override when a row exists, otherwise the file-config value, so a deployment whose instructions still come from YAML reads its own text and a promotion edits that rather than replacing it with one section.
A lookup failure is an error rather than a fallback. The read path treats a failed lookup as an absent row on purpose (a database outage must not blank out an agent's instructions), but a read-modify-write cannot: falling back here would overwrite a stored value with the file value plus the new section.
func (Layer) SetAgentInstructions ¶
SetAgentInstructions stores the customized instruction text as the database override, recording author as its writer. The layer's byte bound is enforced here as well as at each writer, so no path can store a value the composed instructions would then carry into every session.
type OversizeError ¶
type OversizeError struct {
// Size is the byte length of the value that was refused.
Size int
// Limit is the byte limit it exceeded.
Limit int
}
OversizeError refuses a customized-layer write that would push the layer past MaxCustomizedBytes. It names the size, the limit, the overage, and the home the content belongs in instead, so a caller can act on the refusal without reading documentation.
func (*OversizeError) Error ¶
func (e *OversizeError) Error() string
Error implements the error interface.
func (*OversizeError) Over ¶
func (e *OversizeError) Over() int
Over is how many bytes over the limit the refused value was.
type Store ¶
type Store interface {
AgentInstructions(ctx context.Context) (string, error)
SetAgentInstructions(ctx context.Context, value, author string) error
}
Store is the customized agent-instruction layer as its writers need it: read the current text, write a new one.
It is declared here rather than imported so this package does not depend on the toolkit that consumes it -- the knowledge toolkit imports this package for the layer's byte bound, and importing it back would be a cycle. The two declarations are structurally identical, so a Store satisfies knowledge.InstructionsStore and a nil Store converts to a nil one.
func New ¶
New returns the customized agent-instruction layer as a writable store, or nil when store cannot hold a write. A nil return leaves the apply_knowledge agent_instructions sink and its rollback unavailable, so a promotion is refused with the alternative named rather than reporting a success nothing recorded.
defaults are the file-config values a key falls back to (Platform's FileDefaults), and key is the config key the layer lives under (platform.ConfigKeyServerAgentInstructions). Both are passed in so this package stays free of pkg/platform, which composes it.
Source Files