agentsuite

package module
v0.1.0 Latest Latest
Warning

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

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

README

AgentSuite

AgentSuite is a portable, content-addressed definition of one or more related agents and the exact ToolProviders used to construct their runnable sandboxes. Suites are distributed as OCI artifacts and contain a closed graph of agent, ToolProvider, composition, and build-profile manifests.

This standalone Go module, github.com/agent-primitives/suite, provides:

  • public types for suites, agents, ToolProviders, callable Tools, compositions, and build profiles;
  • media types and specification version constants;
  • strict JSON decoding with closed-field and duplicate-key enforcement;
  • JCS canonical encoding and digest calculation;
  • offline validation of extracted content and OCI image-layout directories;
  • optional agent evaluations with ordered cases;
  • closed JSON Schema 2020-12 documents in schema/.

The normative format and conformance requirements are defined in spec.md. Examples and conformance fixtures live in testdata/.

Go package

Use Go 1.26.0 or newer. The module path ends in suite, but the Go package remains agentsuite; use an explicit import alias:

import agentsuite "github.com/agent-primitives/suite"

data, err := agentsuite.Marshal(suite)
if err != nil {
    return err
}

digest, err := agentsuite.Digest(data)

Unmarshal should be used for AgentSuite JSON rather than encoding/json directly when strict format enforcement is required.

ValidatePath validates either an extracted AgentSuite content directory or an OCI image-layout directory and returns a conformance report. Consumers that read loose manifests should use ValidateDirectory to validate extracted content explicitly, without OCI layout auto-detection.

The Go validator compiles evaluation regex assertions with regexp, whose accepted expression syntax is RE2. Validation does not execute evaluations, tools, models or agents, and does not attest runtime or sandbox conformance.

Builders, packers, registry transfer, sandbox-image construction, and builder-owned image metadata are implementation concerns and are not part of this package. Kaimahi's builder-owned sandbox-binding schema remains in its source repository.

Development and releases

See CONTRIBUTING.md for verification, cross-repository go.work development and release policy. The first planned release is v0.1.0; Tom owns releases. Publication is a separate maintainer action, not part of the extraction rehearsal.

Repository extraction does not change schema IDs, media types, format versions, canonical bytes or digests. Go module versions and format versions are independent.

Project policies and provenance

Extracted with portable history from kaimahi-agents/kaimahi. The source MIT copyright attribution is retained in LICENSE. See SECURITY.md for private vulnerability reporting and CODE_OF_CONDUCT.md for the Microsoft community policy.

Documentation

Overview

Package agentsuite defines and validates the draft AgentSuite artifact format.

It contains the portable data model, canonical JSON serialization, schemas, and offline conformance validation. Packing, registry transfer, sandbox construction, and builder-owned image metadata belong to implementations such as kmx.

Index

Constants

View Source 
const (
	DiffAdded               = "added"
	DiffRemoved             = "removed"
	DiffModified            = "modified"
	DiffReportSchemaVersion = "kmx.agentsuite.diff/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"
	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"
	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 ValidateImageReference 

func ValidateImageReference(value string) error

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

Types

type AffectedAgent 

type AffectedAgent struct {
	ID      string   `json:"id"`
	Reasons []string `json:"reasons"`
}

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"`
	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 {
	SchemaVersion string          `json:"schemaVersion"`
	MediaType     string          `json:"mediaType"`
	ID            string          `json:"id"`
	RuntimeBase   []PlatformImage `json:"runtimeBase"`
	Harness       []PlatformImage `json:"harness"`
	SourceEpoch   int64           `json:"sourceEpoch"`
}

type Composition 

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

type CompositionRef 

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

type CompositionSelection 

type CompositionSelection struct {
	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 DiffIdentity 

type DiffIdentity struct {
	Suite          string `json:"suite"`
	SourceType     string `json:"sourceType"`
	ContentDigest  string `json:"contentDigest"`
	ArtifactDigest string `json:"artifactDigest,omitempty"`
}

type DiffLimitError 

type DiffLimitError struct {
	Resource string
	Limit    int
}

func (*DiffLimitError) Error 

func (e *DiffLimitError) Error() string

type DiffReport 

type DiffReport struct {
	SchemaVersion  string          `json:"schemaVersion"`
	Before         DiffIdentity    `json:"before"`
	After          DiffIdentity    `json:"after"`
	Summary        DiffSummary     `json:"summary"`
	Changes        []RecordChange  `json:"changes"`
	AffectedAgents []AffectedAgent `json:"affectedAgents"`
}

func DiffPaths 

func DiffPaths(beforePath, afterPath string) (DiffReport, error)

DiffPaths compares two conformant extracted AgentSuites or local OCI layouts.

func (DiffReport) HasChanges 

func (r DiffReport) HasChanges() bool

type DiffSummary 

type DiffSummary struct {
	Added          int `json:"added"`
	Removed        int `json:"removed"`
	Modified       int `json:"modified"`
	FieldsChanged  int `json:"fieldsChanged"`
	AgentsAffected int `json:"agentsAffected"`
}

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 Extension 

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

type FieldChange 

type FieldChange struct {
	Path   string          `json:"path"`
	Before json.RawMessage `json:"before,omitempty"`
	After  json.RawMessage `json:"after,omitempty"`
}

type FileRef 

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

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"`
}

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"`
	EndpointEnv string   `json:"endpointEnv,omitempty"`
	SecretRefs  []string `json:"secretRefs,omitempty"`
}

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 RecordChange 

type RecordChange struct {
	Type         string        `json:"type"`
	Kind         string        `json:"kind"`
	ID           string        `json:"id"`
	BeforeDigest string        `json:"beforeDigest,omitempty"`
	AfterDigest  string        `json:"afterDigest,omitempty"`
	Fields       []FieldChange `json:"fields"`
}

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"`
}

func ValidateDirectory 

func ValidateDirectory(root string) (*Report, error)

ValidateDirectory validates extracted AgentSuite content without OCI layout auto-detection. Consumers of loose manifests must validate this same view.

func ValidatePath 

func ValidatePath(value string) (*Report, error)

ValidatePath validates either an extracted AgentSuite content directory or an OCI image-layout directory containing one AgentSuite artifact.

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 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"`
	Capabilities             []string                     `json:"capabilities,omitempty"`
	Extensions               []Extension                  `json:"extensions,omitempty"`
}

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.

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.