archetype

Documentation

Overview

Package archetype defines the Agent resource kind: a versioned, addressable description of how an agent runs. An Agent bundles the standing system prompt, the capabilities it may use, the model and loop it runs on, and the skill and memory scope it sees. Promoting archetypes from inline configuration to a stored resource makes them listable, diffable, grant-narrowable, and fleet-syncable like every other resource, and gives a delegation (a spawned specialist) a concrete thing to bind to: a run "as" an Agent is governed by exactly the capabilities the Agent declares.

Index

• Constants
• func RegisterKind(reg *resource.Registry) error
• type Resolved
  • func Flatten(ctx context.Context, store resource.Store, scope resource.Scope, spec Spec) (Resolved, error)
  • func Resolve(ctx context.Context, store resource.Store, scope resource.Scope, name string) (Resolved, error)
  • func (r Resolved) Grant() capability.Grant
• type Spec
  • func DecodeSpec(r resource.Resource) (Spec, error)
  • func (s Spec) Grant() capability.Grant
• type Status
  • func DecodeStatus(r resource.Resource) (Status, error)
  • func (s Status) Encode() (json.RawMessage, error)

Constants

const (
	// GroupVersion is the Agent kind's API group and version.
	GroupVersion = "agent.ionagent.io/v1alpha1"
	// Kind is the resource kind name.
	Kind = "Agent"
)

Functions

func RegisterKind

func RegisterKind(reg *resource.Registry) error

RegisterKind registers the Agent kind so agents can be stored and admitted like any other resource.

Types

type Resolved

type Resolved struct {
	System       string
	Capabilities []string
	Model        string
	Driver       string
	SkillScope   string
	MemoryScope  string
	Tools        []string
	Knowledge    []string
}

Resolved is an Agent flattened to its effective bundle: the Agent's own fields composed with every base it extends. It is what a run is actually configured from, so the runtime, the spawner, and the router all consume Resolved rather than reaching into the composition chain themselves.

func Flatten

func Flatten(ctx context.Context, store resource.Store, scope resource.Scope, spec Spec) (Resolved, error)

Flatten flattens a spec already in hand against store (resolving its Extends chain), without a name of its own. Use it when the Agent spec is already loaded.

func Resolve

func Resolve(ctx context.Context, store resource.Store, scope resource.Scope, name string) (Resolved, error)

Resolve loads the Agent named name from store and flattens its composition chain into the effective bundle. Bases are merged in declared order, then the Agent itself on top: scalar fields take the most-derived non-empty value (the Agent overrides its bases; a later base overrides an earlier one), and the set fields (capabilities, tools, knowledge) are the union. A composition cycle is a terminal error; a diamond (two bases sharing an ancestor) is allowed. A flat Agent that extends nothing resolves to itself.

func (Resolved) Grant

func (r Resolved) Grant() capability.Grant

Grant builds the capability grant for a resolved Agent: the run is admitted only for the capabilities the effective bundle declares.

type Spec

type Spec struct {
	// System is the standing system prompt framing every turn for this agent. Empty
	// uses the host's default prompt.
	System string `json:"system,omitempty"`
	// Capabilities is the exact set of action names a run as this agent may take, the
	// complete record of its authority. A tool the agent does not list is refused at
	// the dispatch waist even though the host offers it, so the Agent resource is the
	// least-privilege boundary. The model call is always permitted; it need not be
	// listed.
	Capabilities []string `json:"capabilities,omitempty"`
	// Model is the provider:model identifier this agent runs on. Empty defers to the
	// host's configured model.
	Model string `json:"model,omitempty"`
	// Driver names the run loop this agent uses (resolved from the driver registry).
	// Empty uses the default general-purpose loop.
	Driver string `json:"driver,omitempty"`
	// SkillScope and MemoryScope bound which skills and memory the agent sees. Empty
	// means the host default scope.
	SkillScope  string `json:"skillScope,omitempty"`
	MemoryScope string `json:"memoryScope,omitempty"`
	// Tools and Knowledge name the tool implementations and knowledge sources this
	// agent is built with, beyond the capability grant (which is the authority to
	// call them). They are carried on the bundle so an Agent fully describes itself;
	// resolving them to concrete implementations is the host's job.
	Tools     []string `json:"tools,omitempty"`
	Knowledge []string `json:"knowledge,omitempty"`
	// Extends names base Agents this one composes from (mixins). The effective Agent
	// is the bases merged in order, then this Agent on top: scalar fields (system,
	// model, driver, scopes) take the most-derived non-empty value, and the set
	// fields (capabilities, tools, knowledge) are the union. Composition lets a
	// specialist be "a base plus overrides" rather than a duplicated full spec, so
	// the archetype set scales without spec sprawl. See Resolve.
	Extends []string `json:"extends,omitempty"`
}

Spec is an Agent's desired shape: how a run as this agent is configured. Every field is optional so a minimal Agent is just a name; the zero Spec runs the default loop with no special capabilities.

func DecodeSpec

func DecodeSpec(r resource.Resource) (Spec, error)

DecodeSpec reads the typed spec from a resource.

func (Spec) Grant

func (s Spec) Grant() capability.Grant

Grant builds the capability grant for a run as this agent from its declared capabilities. It is the authority half of the Agent: the run is admitted only for the actions the Agent lists. A delegate spawned under this Agent narrows from here, never widens.

type Status

type Status struct {
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
}

Status is an Agent's observed state. It is minimal today: an Agent is mostly desired-state configuration, so there is little to observe beyond which spec generation has been reconciled.

func DecodeStatus

func DecodeStatus(r resource.Resource) (Status, error)

DecodeStatus reads the typed status from a resource.

func (Status) Encode

func (s Status) Encode() (json.RawMessage, error)

Encode renders the status for storage.