Crate awaken

Expand description

The awaken facade crate — the primary entry point for building AI agents.

This crate re-exports everything you need from the underlying awaken-* crates so that user code only needs a single dependency. Start with prelude for a one-import convenience layer, or access individual modules directly.

§Quick start

use awaken::prelude::*;
use awaken::engine::GenaiExecutor;

let runtime = AgentRuntimeBuilder::new()
    .with_agent_spec(AgentSpec::new("assistant").with_model_id("gpt-4o-mini"))
    .with_provider("openai", Arc::new(GenaiExecutor::new()))
    .with_model(ModelSpec::new("gpt-4o-mini", "openai", "gpt-4o-mini"))
    .build()?;

let activation = RunActivation::new("thread-1", vec![Message::user("Hello")])
    .with_agent_id("assistant");

let result = runtime.run_to_completion(activation).await?;
let response = result.response;

§Module layout

Path	Description
`prelude`	One-stop import for common agent-building types
`contract`	Core protocol traits: tools, inference, events, lifecycle
`model`	Data-model primitives: phases, effects, scheduled actions
`state`	State key/value types and mutation primitives
`registry`	Agent registry and resolution
`builder`	`AgentRuntimeBuilder` — fluent runtime construction
`plugins`	Plugin trait and descriptor types
`phase`	Phase execution context and hooks
`engine`	Low-level agent execution engine
`stores`	Storage backend implementations
`server`	HTTP server layer (feature `server`)

Re-exports§

pub use awaken_stores as stores;
pub use awaken_ext_generative_ui as ext_generative_ui;
pub use awaken_ext_mcp as ext_mcp;
pub use awaken_ext_observability as ext_observability;
pub use awaken_ext_permission as ext_permission;
pub use awaken_ext_reminder as ext_reminder;
pub use awaken_ext_skills as ext_skills;
pub use awaken_server as server;

Modules§

agent: Agent configuration and instance types.
builder: Fluent builder for constructing an AgentRuntime. Fluent builder API for constructing AgentRuntime.
context: Execution context and request/response wrappers. Context management: compaction, summarization, truncation, and plugin state.
contract: Core protocol traits: tools, inference, events, lifecycle, storage contracts.
engine: Low-level agent execution engine. Engine layer: genai-backed LLM executor and type conversion.
execution: Execution-environment helpers and run orchestration. Tool execution concerns: executors.
extensions: Extension-point traits for integrating with the runtime. Bundled extensions for the awaken runtime.
loop_runner: Agent run-loop runner. Minimal sequential agent loop driven by state machines.
model: Data-model primitives: phases, effects, scheduled actions.
phase: Phase execution context, hooks, and phase-level runtime.
plugins: Plugin loading, descriptor registry, and registration API.
policies: Stop policies and run-termination conditions. Stop condition policy system and built-in policies.
prelude: One-import convenience module for awaken.
registry: Agent registry lookup and resolution. Registry traits, in-memory implementations, and agent resolution.
registry_spec: Agent-registry specification types. Serializable agent definition — pure data, no trait objects.
runtime: AgentRuntime and RunActivation — the top-level run API.
server_contract: Server/store-owned contract surfaces relocated out of contract::*.
state: Combined state types from both the contract and runtime layers.

Structs§

A2aServerSpec: Named A2A server connection profile used by admin/control-plane surfaces.
AgentRuntime: Top-level agent runtime. Manages runs across threads.
AgentRuntimeBuilder: Fluent API for constructing an AgentRuntime.
AgentSpec: Serializable agent definition referencing registries by ID.
AgentSpecPatch: Patch for built-in agent customization.
CancellationToken: A cooperative cancellation token.
CommitEvent
ConfigRecord: Wrapper carrying a spec plus provenance + lifecycle metadata.
ExecutionEnv: Per-run execution environment.
FailedScheduledActions
MockProviderProfile: Explicit mock provider wiring for tests and local development.
Modalities: Set of modalities a model accepts on input and produces on output.
ModelSpec: Serializable model offering: addressing (id, provider, upstream model), intrinsic capabilities (context window, max output tokens, modalities, knowledge cutoff), and per-million-token pricing.
MutationBatch: A batch of state mutation operations.
NoConfigPatch: Empty patch for spec types that do not support field-level overrides.
PendingScheduledActions
PersistedState
PhaseContext: Execution context passed to phase hooks and action handlers.
PhaseRuntime
PluginDescriptor
PluginRegistrar
ProviderRemovalImpact
ProviderRemovalPreview
RecordMeta: Provenance + lifecycle metadata for a stored spec.
RedactedString: String wrapper whose Debug/Display implementations never reveal the underlying value, and whose buffer is zeroized on drop.
RegistryResourceRef
RegistryValidationError
ResolvedAgent: A fully resolved agent: all capabilities + plugin environment, ready to run.
RunActivation: Owned request to execute or resume a run.
RuntimeRegistryUpdate
ScopeContext
ScopeId
ScopedConfigStore
ScopedMailboxStore
ScopedOutboxStore
ScopedProtocolReplayLog
ScopedThreadRunStore
SerializableRegistryDiagnostic
SkillArgumentSpec: Formal argument metadata for a skill activation.
SkillSpec: ConfigStore representation of a skill.
SkillSpecPatch
Snapshot
StateCommand: A command that carries state mutations, scheduled actions, and effects.
StateKeyOptions
StateMap
StateStore
TypedEffect

Enums§

BuildError: Error returned when the builder cannot construct the runtime.
ConfigRecordError: Error returned while decoding a ConfigRecord or applying its overrides.
ConfigValidationError
JsonValue: Represents any valid JSON value.
KeyScope: Lifetime scope for a state key.
MergeStrategy: Parallel merge strategy for a state key.
Modality: Input/output modality supported by a model.
Phase: Lifecycle phase within an agent run.
ProviderRemovalPolicy
RecordSource: Who wrote this record into ConfigStore.
RegistryDiagnostic
RegistryDiagnosticSeverity
RegistryUpdateError
RequestSurface
RuntimeError: Runtime-specific errors that wrap StateError and add variants for agent resolution and run management.
SkillSpecContext: Execution mode for a config-managed skill.
StateError
UnknownFieldPolicy: Unknown-field behavior for a serializable config surface.
UnknownKeyPolicy

Constants§

A2A_SERVER_ID_OPTION
AGENT_SPEC_PATCH_UNKNOWN_FIELD_POLICY
AGENT_SPEC_UNKNOWN_FIELD_POLICY: AgentSpec and AgentSpecPatch reject unknown fields.
DEFAULT_MAX_PHASE_ROUNDS
DEFAULT_SCOPE_ID
MODEL_SPEC_UNKNOWN_FIELD_POLICY
PROVIDER_SPEC_UNKNOWN_FIELD_POLICY: ProviderSpec’s serde implementation is intentionally lenient for read-time compatibility, but config write/validate surfaces reject unknown fields so operators do not persist silently ignored provider settings.
SKILL_SPEC_UNKNOWN_FIELD_POLICY

Traits§

AgentResolver: Resolves an agent by ID, producing a ready-to-execute config + environment.
CommitHook
ConfigRecordMerge: Spec types that can apply RecordMeta::user_overrides at read time.
ConfigStore: Async CRUD store for namespaced JSON configuration documents.
EffectSpec
PhaseHook
Plugin
PluginConfigKey: Typed plugin configuration key.
PreparedSkillSpecs: Prepared, validated skill registry replacement.
ScheduledActionSpec
SkillSpecSink: Sink used by runtime/config managers that publish DB-managed skill specs to a live skill registry without depending on the concrete skills extension.
StateKey
ToolGateHook
TypedEffectHandler
TypedScheduledActionHandler
TypedTool: A strongly-typed tool trait that derives its descriptor schema from Args.

Functions§

a2a_server_id
decode_config_record: Decode a value into ConfigRecord<T>, accepting either an envelope or a legacy bare spec. This does not validate RecordMeta::user_overrides.
diagnose_agent_spec
diagnose_registry_set
diagnose_registry_set_serializable
effective_config_record: Apply RecordMeta::user_overrides to the record’s base spec.
effective_visible_config_records: Decode visible records and return their effective specs.
generate_tool_schema: Generate a JSON Schema for T that is suitable for LLM tool calling.
merge_agent_spec: Apply a AgentSpecPatch on top of a base AgentSpec, producing the effective spec passed to the resolver.
merge_skill_spec
preview_provider_removal
rebuild_agent_model_provider_registries
sanitize_for_llm: Sanitize a JSON Schema value in-place to be LLM-friendly.
scoped_key
set_a2a_server_id
unscoped_key
validate_against_schema: Validate args against a JSON Schema, returning an error with joined messages on failure.
validate_agent_spec: Validate and decode an AgentSpec.
validate_agent_spec_patch: Validate and decode an AgentSpecPatch.
validate_config_record: Validate and decode a config record envelope, accepting legacy bare specs. RecordMeta::user_overrides must decode as the patch type for T.
validate_config_record_overrides: Validate RecordMeta::user_overrides for an already decoded record.
validate_model_spec: Validate and decode a ModelSpec from JSON for config write surfaces.
validate_provider_spec: Validate and decode a ProviderSpec for config write surfaces.
validate_skill_spec: Validate and decode a SkillSpec for config write surfaces.
validate_unique_model_ids: Validate that a slice of ModelSpec contains no duplicate id values.

Type Aliases§

ScopedVersionedRegistry

Crate awaken

Crate awaken Copy item path

§Quick start

§Module layout

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate awaken