core

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 21, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package core defines portable AgentSuite manifests, profiles, evaluation definitions, strict JSON and content identity helpers. It does not load directories or OCI layouts, verify evidence, or execute agents.

Index

Constants

View Source 
const (
	ExecutionHTTPV1       = "http-v1"
	AgentKitMountedConfig = "agentkit-v0-mounted-v1"
)
View Source 
const (
	SpecVersion = "1.0.0-draft"

	LayoutVersion = "1.0.0"

	MediaTypeArtifact                = "application/vnd.agentsuite.suite.v1"
	MediaTypeEmptyConfig             = "application/vnd.oci.empty.v1+json"
	MediaTypeContent                 = "application/vnd.agentsuite.content.v1.tar+gzip"
	MediaTypeSuite                   = "application/vnd.agentsuite.manifest.v1+json"
	MediaTypeAgent                   = "application/vnd.agentsuite.agent.v1+json"
	MediaTypePolicyV1                = "application/vnd.agentsuite.policy.v1+json"
	MediaTypePolicyV2                = "application/vnd.agentsuite.policy.v2+json"
	MediaTypeEvaluationIndex         = "application/vnd.agentsuite.eval.index.v1+json"
	MediaTypeEvaluationCase          = "application/vnd.agentsuite.eval.case.v1+json"
	MediaTypeToolProviderCatalog     = "application/vnd.agentsuite.tool.provider.catalog.v1+json"
	MediaTypeToolProvider            = "application/vnd.agentsuite.tool.provider.v1+json"
	MediaTypeToolProviderComposition = "application/vnd.agentsuite.tool.provider.composition.v1+json"
	MediaTypeComposition             = "application/vnd.agentsuite.composition.v1+json"
	MediaTypeBuildProfile            = "application/vnd.agentsuite.build.profile.v1+json"
	MediaTypeRuntimeProfile          = "application/vnd.agentsuite.runtime.profile.v1+json"
	MediaTypeInstructions            = "text/markdown; charset=utf-8"
	MediaTypeJSONSchema              = "application/schema+json"

	ExecutionSharedSandbox = "shared-sandbox"
)

Variables

This section is empty.

Functions

func DescriptorSizeAndDigestMatch 

func DescriptorSizeAndDigestMatch(data []byte, descriptor Descriptor) bool

DescriptorSizeAndDigestMatch performs the cheap length and raw-byte digest comparison against descriptor, without canonicalizing data at all. It lets a caller reject a size/digest-mismatched document before investing in full JSON parsing (strict decoding, canonicalization, or reflection-based field checks). It does not confirm that data is itself stored in canonical form; callers that parse data after this check still need MatchesCanonicalDescriptor to enforce that invariant.

func Digest 

func Digest(data []byte) (string, error)

Digest returns the SHA-256 digest of the JCS representation of data.

func IsValidDigest 

func IsValidDigest(value string) bool

IsValidDigest reports whether value is a canonical AgentSuite SHA-256 digest.

func Marshal 

func Marshal(value any) ([]byte, error)

Marshal serializes value as JSON Canonicalization Scheme (JCS) JSON.

func MatchesCanonicalDescriptor 

func MatchesCanonicalDescriptor(data []byte, descriptor Descriptor) bool

MatchesCanonicalDescriptor reports whether data is itself stored as its own RFC 8785 JCS canonical bytes, and whether descriptor's digest and size describe that same canonical representation. A descriptor binding canonical identity is satisfied only when the stored bytes are already canonical: differently formatted (for example pretty-printed) but semantically equivalent JSON is rejected, since a consumer must be able to load the referenced bytes directly without re-canonicalizing them first. Callers outside this package (for example builders that re-read pinned child manifests) should use this instead of re-deriving digest/size checks by hand, so every consumer enforces the same stored-byte identity rule.

func Unmarshal 

func Unmarshal(data []byte, out any) error

Unmarshal decodes one strict AgentSuite JSON document.

It rejects duplicate or unknown fields, invalid UTF-8, lossy JCS number representations, trailing values, and documents exceeding the format's declared implementation limits.

func ValidateExecutionContract 

func ValidateExecutionContract(c ExecutionContract) error

func ValidateImageReference 

func ValidateImageReference(value string) error

ValidateImageReference requires a registry-qualified, sha256-digested image reference with a valid registry authority.

Types

type Agent 

type Agent struct {
	SchemaVersion string                    `json:"schemaVersion"`
	MediaType     string                    `json:"mediaType"`
	ID            string                    `json:"id"`
	Description   string                    `json:"description,omitempty"`
	Instructions  FileRef                   `json:"instructions"`
	Model         ModelRequirement          `json:"model"`
	ToolProviders []ToolProviderRequirement `json:"toolProviders,omitempty"`
	Invokes       []AgentInvoke             `json:"invokes,omitempty"`
	Evals         []FileRef                 `json:"evals,omitempty"`
	Policy        *FileRef                  `json:"policy,omitempty"`
	Extensions    []Extension               `json:"extensions,omitempty"`
}

type AgentInvoke 

type AgentInvoke struct {
	Agent         string `json:"agent"`
	MaxConcurrent int    `json:"maxConcurrent,omitempty"`
	MaxDepth      int    `json:"maxDepth,omitempty"`
}

type AgentPlatform 

type AgentPlatform struct {
	ID        string     `json:"id"`
	Platforms []Platform `json:"platforms"`
}

type BrokeredCredential 

type BrokeredCredential struct {
	Resolution string `json:"resolution"`
	BindingRef string `json:"bindingRef"`
}

BrokeredCredential declares that credential resolution and injection for a delegated-user authorization requirement are brokered entirely by the runtime. It never contains a credential value.

type BuildProfile 

type BuildProfile struct {
	Execution     *ExecutionContract `json:"execution,omitempty"`
	SchemaVersion string             `json:"schemaVersion"`
	MediaType     string             `json:"mediaType"`
	ID            string             `json:"id"`
	RuntimeBase   []PlatformImage    `json:"runtimeBase"`
	Harness       []PlatformImage    `json:"harness"`
	SourceEpoch   int64              `json:"sourceEpoch"`
}

func (*BuildProfile) UnmarshalJSON 

func (p *BuildProfile) UnmarshalJSON(data []byte) error

UnmarshalJSON rejects a null execution property; a pointer decoder would otherwise treat it as omission without invoking the contract's decoder.

type Composition 

type Composition struct {
	RuntimeProfile string                 `json:"runtimeProfile,omitempty"`
	SchemaVersion  string                 `json:"schemaVersion"`
	MediaType      string                 `json:"mediaType"`
	Agent          string                 `json:"agent"`
	Platform       Platform               `json:"platform"`
	BuildProfile   string                 `json:"buildProfile"`
	ToolProviders  []ResolvedToolProvider `json:"toolProviders"`
}

func (*Composition) UnmarshalJSON 

func (c *Composition) UnmarshalJSON(data []byte) error

type CompositionRef 

type CompositionRef struct {
	RuntimeProfile string     `json:"runtimeProfile,omitempty"`
	Agent          string     `json:"agent"`
	Platform       Platform   `json:"platform"`
	Path           string     `json:"path"`
	Descriptor     Descriptor `json:"descriptor"`
}

func (*CompositionRef) UnmarshalJSON 

func (c *CompositionRef) UnmarshalJSON(data []byte) error

type CompositionSelection 

type CompositionSelection struct {
	RuntimeProfile string   `json:"runtimeProfile,omitempty"`
	Agent          string   `json:"agent"`
	Platform       Platform `json:"platform"`
	BuildProfile   string   `json:"buildProfile"`
	Digest         string   `json:"digest"`
}

type DelegatedAuthorization 

type DelegatedAuthorization struct {
	Service    string             `json:"service"`
	Scope      string             `json:"scope"`
	Credential BrokeredCredential `json:"credential"`
}

DelegatedAuthorization declares that a Tool requires delegated-user authorization before it may be called. It never contains a credential value, consent state, token lifecycle state, or a deployment-specific Connection identifier; the deployment/runtime resolves the requirement to a verified requester and a live user-owned connection.

type Descriptor 

type Descriptor struct {
	MediaType   string            `json:"mediaType"`
	Digest      string            `json:"digest"`
	Size        int64             `json:"size"`
	Annotations map[string]string `json:"annotations,omitempty"`
}

Descriptor is an OCI-compatible content descriptor: a named, nested property on a suite-local reference that carries the referenced content's media type, digest, and size, plus optional descriptive annotations. Outer selector fields (such as id, version, agent, platform, and path) stay on the enclosing reference; Descriptor only describes the referenced bytes.

func (*Descriptor) UnmarshalJSON 

func (d *Descriptor) UnmarshalJSON(data []byte) error

UnmarshalJSON requires mediaType, digest, and size to be present in the document. A present size of zero is a legitimate empty-content descriptor; an omitted size is rejected. Both would otherwise decode to the same Go zero value, so presence is checked explicitly against the raw fields before the normal typed decode. It also rejects any object key outside the closed descriptor shape, and rejects an explicit JSON null for mediaType, digest, size, or a present annotations key, which would otherwise silently decode to the same Go zero values as legitimate values (notably null size and size: 0 both decode to 0).

type EnvironmentName 

type EnvironmentName struct {
	Name     string `json:"name"`
	Required bool   `json:"required,omitempty"`
	Secret   bool   `json:"secret,omitempty"`
	Delivery string `json:"delivery,omitempty"`
}

type EvaluationAssertion 

type EvaluationAssertion struct {
	ID           string `json:"id"`
	Type         string `json:"type"`
	Critical     *bool  `json:"critical,omitempty"`
	Value        string `json:"value,omitempty"`
	Pattern      string `json:"pattern,omitempty"`
	Tool         string `json:"tool,omitempty"`
	Rubric       string `json:"rubric,omitempty"`
	MinScore     *int   `json:"minScore,omitempty"`
	JudgeModel   string `json:"judgeModel,omitempty"`
	JudgeVersion string `json:"judgeVersion,omitempty"`
}

type EvaluationCase 

type EvaluationCase struct {
	SchemaVersion string                `json:"schemaVersion"`
	MediaType     string                `json:"mediaType"`
	ID            string                `json:"id"`
	Input         string                `json:"input"`
	Runs          *int                  `json:"runs,omitempty"`
	MinPasses     *int                  `json:"minPasses,omitempty"`
	Assertions    []EvaluationAssertion `json:"assertions"`
}

type EvaluationIndex 

type EvaluationIndex struct {
	SchemaVersion string           `json:"schemaVersion"`
	MediaType     string           `json:"mediaType"`
	Agent         string           `json:"agent"`
	Cases         []FileRef        `json:"cases"`
	Limits        EvaluationLimits `json:"limits"`
}

type EvaluationLimits 

type EvaluationLimits struct {
	MaxCases     int `json:"maxCases"`
	MaxCaseBytes int `json:"maxCaseBytes"`
}

type EvidenceImplementation 

type EvidenceImplementation struct {
	ID      string `json:"id"`
	Version string `json:"version"`
	Digest  string `json:"digest"`
}

type ExecutionContract 

type ExecutionContract struct {
	Configuration string           `json:"configuration,omitempty"`
	Kind          string           `json:"kind"`
	Protocol      string           `json:"protocol"`
	Port          int              `json:"port"`
	HealthPath    string           `json:"healthPath"`
	Inputs        []ExecutionInput `json:"inputs"`
}

ExecutionContract is an experimental declaration of a built image's interface. The configuration name selects exact semantics, not arbitrary process overrides. It does not select a member runtime or require an image for native execution.

func (ExecutionContract) MarshalJSON 

func (c ExecutionContract) MarshalJSON() ([]byte, error)

MarshalJSON encodes nil Inputs as the required empty array without changing c.

func (*ExecutionContract) UnmarshalJSON 

func (c *ExecutionContract) UnmarshalJSON(data []byte) error

UnmarshalJSON preserves required-field presence before decoding zero values.

type ExecutionInput 

type ExecutionInput struct {
	Name        string `json:"name"`
	Environment string `json:"environment"`
	Secret      bool   `json:"secret"`
}

func (*ExecutionInput) UnmarshalJSON 

func (input *ExecutionInput) UnmarshalJSON(data []byte) error

UnmarshalJSON requires an explicit secret classification, including false.

type Extension 

type Extension struct {
	Name     string `json:"name"`
	Critical bool   `json:"critical"`
	Digest   string `json:"digest,omitempty"`
}

type FileRef 

type FileRef struct {
	Path       string     `json:"path"`
	Descriptor Descriptor `json:"descriptor"`
}

type InferenceRequirements 

type InferenceRequirements struct {
	API           string `json:"api"`
	ContextTokens int    `json:"contextTokens"`
	OutputTokens  int    `json:"outputTokens"`
	Streaming     bool   `json:"streaming"`
	ToolCalling   bool   `json:"toolCalling"`
}

InferenceRequirements describes the model API needed by an agent, not a particular model deployment. Token limits refer to total context and output.

func (InferenceRequirements) Match 

func (r InferenceRequirements) Match(available InferenceRequirements) error

Match uses explicitly declared connection capabilities. It does not infer token limits from /models or claim that operator declarations are verified.

func (*InferenceRequirements) UnmarshalJSON 

func (r *InferenceRequirements) UnmarshalJSON(data []byte) error

UnmarshalJSON requires explicit capability booleans even when they are false.

func (InferenceRequirements) Validate 

func (r InferenceRequirements) Validate() error

type InventoryEntry 

type InventoryEntry struct {
	Path       string `json:"path"`
	Type       string `json:"type"`
	Mode       uint32 `json:"mode"`
	UID        int    `json:"uid"`
	GID        int    `json:"gid"`
	Size       int64  `json:"size,omitempty"`
	Digest     string `json:"digest,omitempty"`
	LinkTarget string `json:"linkTarget,omitempty"`
	Component  string `json:"component,omitempty"`
}

func (*InventoryEntry) UnmarshalJSON 

func (e *InventoryEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON requires path, type, mode, uid, and gid to be present and non-null. Mode 0 and uid/gid 0 are legitimate authored values, so an omitted or null property would otherwise be indistinguishable from them after typed decoding. The shared strict decoder still rejects unknown and duplicate keys.

type ManifestRef 

type ManifestRef struct {
	ID         string     `json:"id"`
	Version    string     `json:"version,omitempty"`
	Path       string     `json:"path"`
	Descriptor Descriptor `json:"descriptor"`
}

type ModelRequirement 

type ModelRequirement struct {
	Protocol     string                 `json:"protocol"`
	Model        string                 `json:"model,omitempty"`
	Capabilities *InferenceRequirements `json:"capabilities,omitempty"`
	EndpointEnv  string                 `json:"endpointEnv,omitempty"`
	SecretRefs   []string               `json:"secretRefs,omitempty"`
}

func (*ModelRequirement) UnmarshalJSON 

func (m *ModelRequirement) UnmarshalJSON(data []byte) error

UnmarshalJSON checks property presence before optional zero values can erase the model schema's exclusive selection and deployment-binding restrictions.

type NetworkAccess 

type NetworkAccess struct {
	Scheme string `json:"scheme"`
	Host   string `json:"host"`
	Port   int    `json:"port"`
}

type Platform 

type Platform struct {
	OS           string `json:"os"`
	Architecture string `json:"architecture"`
	Variant      string `json:"variant,omitempty"`
}

func (Platform) String 

func (p Platform) String() string

type PlatformImage 

type PlatformImage struct {
	Platform Platform   `json:"platform"`
	ImageRef string     `json:"imageRef"`
	Image    Descriptor `json:"image"`
}

type RemoteHeader 

type RemoteHeader struct {
	Name      string       `json:"name"`
	SecretRef SecretKeyRef `json:"secretRef"`
}

type RemoteNetworkRequirement 

type RemoteNetworkRequirement struct {
	DestinationRef string `json:"destinationRef"`
}

type RemoteTimeouts 

type RemoteTimeouts struct {
	ConnectMilliseconds int `json:"connectMilliseconds"`
	RequestMilliseconds int `json:"requestMilliseconds"`
}

type RemoteToolProvider 

type RemoteToolProvider struct {
	Transport    string                     `json:"transport"`
	EndpointRef  string                     `json:"endpointRef"`
	Headers      []RemoteHeader             `json:"headers,omitempty"`
	Network      []RemoteNetworkRequirement `json:"network"`
	Timeouts     RemoteTimeouts             `json:"timeouts"`
	Cancellation string                     `json:"cancellation"`
	Connection   string                     `json:"connection"`
}

type Report 

type Report struct {
	Name                     string                 `json:"name"`
	Agents                   int                    `json:"agents"`
	ToolProviders            int                    `json:"toolProviders"`
	ToolProviderCompositions int                    `json:"toolProviderCompositions"`
	Compositions             int                    `json:"compositions"`
	Capabilities             []string               `json:"capabilities"`
	AgentPlatforms           []AgentPlatform        `json:"agentPlatforms"`
	CompositionSelections    []CompositionSelection `json:"compositionSelections"`
}

type ResolvedToolProvider 

type ResolvedToolProvider struct {
	ID             string `json:"id"`
	Version        string `json:"version"`
	ManifestDigest string `json:"manifestDigest"`
	VariantDigest  string `json:"variantDigest,omitempty"`
	ExecutionMode  string `json:"executionMode"`
}

type RuntimeProfile 

type RuntimeProfile struct {
	SchemaVersion    string                 `json:"schemaVersion"`
	MediaType        string                 `json:"mediaType"`
	ID               string                 `json:"id"`
	Runtime          EvidenceImplementation `json:"runtime"`
	Harness          EvidenceImplementation `json:"harness"`
	Renderer         EvidenceImplementation `json:"renderer"`
	ConfigurationABI string                 `json:"configurationABI"`
	ImageRequired    bool                   `json:"imageRequired"`
}

RuntimeProfile pins execution requirements without overriding member content. ConfigurationABI is an opaque consumer-owned identifier, not a portable implementation catalog. Validation declares consistency, not runtime support.

func (*RuntimeProfile) UnmarshalJSON 

func (p *RuntimeProfile) UnmarshalJSON(data []byte) error

type RuntimeRequirement 

type RuntimeRequirement struct {
	ABI           string   `json:"abi"`
	ABIVersion    string   `json:"abiVersion,omitempty"`
	CPUBaseline   string   `json:"cpuBaseline"`
	RequiredPaths []string `json:"requiredBasePaths,omitempty"`
}

type SecretKeyRef 

type SecretKeyRef struct {
	Name string `json:"name"`
	Key  string `json:"key"`
}

type Suite 

type Suite struct {
	SchemaVersion            string                       `json:"schemaVersion"`
	MediaType                string                       `json:"mediaType"`
	Name                     string                       `json:"name"`
	Agents                   []ManifestRef                `json:"agents"`
	ToolProviderCatalog      ManifestRef                  `json:"toolProviderCatalog"`
	ToolProviderCompositions []ToolProviderCompositionRef `json:"toolProviderCompositions,omitempty"`
	Compositions             []CompositionRef             `json:"compositions"`
	BuildProfiles            []ManifestRef                `json:"buildProfiles"`
	RuntimeProfiles          []ManifestRef                `json:"runtimeProfiles,omitempty"`
	Capabilities             []string                     `json:"capabilities,omitempty"`
	Extensions               []Extension                  `json:"extensions,omitempty"`
}

func (*Suite) UnmarshalJSON 

func (s *Suite) UnmarshalJSON(data []byte) error

type Tool 

type Tool struct {
	Name                   string                  `json:"name"`
	Description            string                  `json:"description,omitempty"`
	InputSchema            FileRef                 `json:"inputSchema"`
	OutputSchema           *FileRef                `json:"outputSchema,omitempty"`
	Effects                []string                `json:"effects,omitempty"`
	Effect                 string                  `json:"effect,omitempty"`
	Approval               string                  `json:"approval,omitempty"`
	DelegatedAuthorization *DelegatedAuthorization `json:"delegatedAuthorization,omitempty"`
}

Tool is one model-callable function exposed by a ToolProvider.

type ToolProvider 

type ToolProvider struct {
	SchemaVersion string                `json:"schemaVersion"`
	MediaType     string                `json:"mediaType"`
	ID            string                `json:"id"`
	Version       string                `json:"version"`
	Retained      *bool                 `json:"retained,omitempty"`
	Protocol      string                `json:"protocol"`
	Revision      string                `json:"revision"`
	Tools         []Tool                `json:"tools"`
	Variants      []ToolProviderVariant `json:"variants,omitempty"`
	Remote        *RemoteToolProvider   `json:"remote,omitempty"`
	Extensions    []Extension           `json:"extensions,omitempty"`
}

ToolProvider is a versioned contract and its bundled or remote implementations. The abstraction is protocol-neutral; the declared protocol contributes to identity.

func (*ToolProvider) UnmarshalJSON 

func (p *ToolProvider) UnmarshalJSON(data []byte) error

UnmarshalJSON preserves presence-sensitive provider constraints before slices and pointers can turn explicit empty/null properties into omitted values.

type ToolProviderCatalog 

type ToolProviderCatalog struct {
	SchemaVersion string        `json:"schemaVersion"`
	MediaType     string        `json:"mediaType"`
	ToolProviders []ManifestRef `json:"toolProviders"`
}

type ToolProviderComposition 

type ToolProviderComposition struct {
	SchemaVersion  string   `json:"schemaVersion"`
	MediaType      string   `json:"mediaType"`
	ID             string   `json:"id"`
	Version        string   `json:"version"`
	ManifestDigest string   `json:"manifestDigest"`
	Platform       Platform `json:"platform"`
	VariantDigest  string   `json:"variantDigest"`
	BuildProfile   string   `json:"buildProfile"`
}

type ToolProviderCompositionRef 

type ToolProviderCompositionRef struct {
	ID         string     `json:"id"`
	Version    string     `json:"version"`
	Platform   Platform   `json:"platform"`
	Path       string     `json:"path"`
	Descriptor Descriptor `json:"descriptor"`
}

type ToolProviderDependency 

type ToolProviderDependency struct {
	ID            string `json:"id"`
	Version       string `json:"version"`
	VariantDigest string `json:"variantDigest"`
}

type ToolProviderRequirement 

type ToolProviderRequirement struct {
	ID            string `json:"id"`
	Version       string `json:"version"`
	ExecutionMode string `json:"executionMode"`
}

type ToolProviderVariant 

type ToolProviderVariant struct {
	Platform      Platform                 `json:"platform"`
	VariantDigest string                   `json:"variantDigest"`
	InstallRoot   string                   `json:"installRoot"`
	Relocatable   bool                     `json:"relocatable,omitempty"`
	PayloadRoot   string                   `json:"payloadRoot"`
	Entrypoint    string                   `json:"entrypoint"`
	Arguments     []string                 `json:"arguments,omitempty"`
	SearchPath    []string                 `json:"searchPath,omitempty"`
	Environment   []EnvironmentName        `json:"environment,omitempty"`
	WritablePaths []string                 `json:"writablePaths,omitempty"`
	Network       []NetworkAccess          `json:"network,omitempty"`
	Runtime       RuntimeRequirement       `json:"runtime"`
	Files         []InventoryEntry         `json:"files"`
	Dependencies  []ToolProviderDependency `json:"dependencies,omitempty"`
	SBOM          *Descriptor              `json:"sbom,omitempty"`
	Provenance    *Descriptor              `json:"provenance,omitempty"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.