Struct AgentSpec 

pub struct AgentSpec {

    pub id: String,
    pub model_id: String,
    pub system_prompt: String,
    pub max_rounds: usize,
    pub max_continuation_retries: usize,
    pub context_policy: Option<ContextWindowPolicy>,
    pub reasoning_effort: Option<ReasoningEffort>,
    pub plugin_ids: Vec<String>,
    pub active_hook_filter: HashSet<String>,
    pub allowed_tools: Option<Vec<String>>,
    pub excluded_tools: Option<Vec<String>>,
    pub endpoint: Option<RemoteEndpoint>,
    pub delegates: Vec<String>,
    pub sections: HashMap<String, Value>,
    pub registry: Option<String>,
}

Serializable agent definition referencing registries by ID.

Can be saved to JSON, loaded from config files, or transmitted over the network. Resolved at runtime via the resolve pipeline into a ResolvedAgent.

Also serves as the runtime behavior configuration passed to hooks via PhaseContext.agent_spec. Plugins read their typed config via spec.config::<K>().

Fields

id: String

Unique agent identifier.

model_id: String

ModelRegistry ID — resolved to a runtime model binding.

system_prompt: String

System prompt sent to the LLM.

max_rounds: usize

Maximum inference rounds before the agent stops.

max_continuation_retries: usize

Maximum continuation retries for truncated LLM responses.

context_policy: Option<ContextWindowPolicy>

Context window management policy. None disables compaction and truncation.

reasoning_effort: Option<ReasoningEffort>

Default reasoning effort for this agent. None means no thinking/reasoning. Can be overridden per-run via InferenceOverride or per-step via plugins.

plugin_ids: Vec<String>

PluginRegistry IDs — resolved at build time.

active_hook_filter: HashSet<String>

Runtime hook filter: only hooks from plugins in this set will run. Empty = no filtering (all loaded plugins’ hooks run). Distinct from plugin_ids which controls which plugins are loaded.

allowed_tools: Option<Vec<String>>

Allowed tool IDs (whitelist). None = all tools.

excluded_tools: Option<Vec<String>>

Excluded tool IDs (blacklist). Applied after allowed_tools.

endpoint: Option<RemoteEndpoint>

Optional remote endpoint. If set, this agent runs on a remote backend. If None, this agent runs locally.

delegates: Vec<String>

IDs of sub-agents this agent can delegate to. Each ID must be a registered agent in the AgentSpecRegistry.

sections: HashMap<String, Value>

Plugin-specific configuration sections (keyed by PluginConfigKey::KEY).

registry: Option<String>

Registry source this agent was loaded from. None for locally defined agents; Some("cloud") for agents from the “cloud” registry.

Implementations

impl AgentSpec

pub fn new(id: impl Into<String>) -> AgentSpec

Create a new agent spec with default settings.

Examples

use awaken_contract::registry_spec::AgentSpec;

let spec = AgentSpec::new("assistant")
    .with_model_id("gpt-4o-mini")
    .with_system_prompt("You are helpful.")
    .with_max_rounds(10);
assert_eq!(spec.id, "assistant");
assert_eq!(spec.model_id, "gpt-4o-mini");
assert_eq!(spec.system_prompt, "You are helpful.");
assert_eq!(spec.max_rounds, 10);

pub fn config<K>(&self) -> Result<<K as PluginConfigKey>::Config, StateError>

where K: PluginConfigKey,

Read a typed plugin config section. Returns Config::default() if the section is missing. Returns error if the section exists but fails to deserialize.

pub fn set_config<K>( &mut self, config: <K as PluginConfigKey>::Config, ) -> Result<(), StateError>

where K: PluginConfigKey,

Set a typed plugin config section.

pub fn with_model_id(self, model_id: impl Into<String>) -> AgentSpec

pub fn with_system_prompt(self, prompt: impl Into<String>) -> AgentSpec

pub fn with_max_rounds(self, n: usize) -> AgentSpec

pub fn with_reasoning_effort(self, effort: ReasoningEffort) -> AgentSpec

pub fn with_hook_filter(self, plugin_id: impl Into<String>) -> AgentSpec

pub fn with_config<K>( self, config: <K as PluginConfigKey>::Config, ) -> Result<AgentSpec, StateError>

where K: PluginConfigKey,

Set a typed plugin config section (builder variant).

pub fn with_delegate(self, agent_id: impl Into<String>) -> AgentSpec

pub fn with_endpoint(self, endpoint: RemoteEndpoint) -> AgentSpec

pub fn with_section(self, key: impl Into<String>, value: Value) -> AgentSpec

Set a raw JSON section (for tests or untyped usage).

Trait Implementations

impl Clone for AgentSpec

fn clone(&self) -> AgentSpec

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AgentSpec

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for AgentSpec

fn default() -> AgentSpec

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for AgentSpec

fn deserialize<__D>( __deserializer: __D, ) -> Result<AgentSpec, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl JsonSchema for AgentSpec

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl Serialize for AgentSpec

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.