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_binding("gpt-4o-mini", ModelBinding {
        provider_id: "openai".into(),
        upstream_model: "gpt-4o-mini".into(),
    })
    .build()?;

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

let result = runtime.run_to_completion(request).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 RunRequest — the top-level run API.
state: Combined state types from both the contract and runtime layers.

Structs§

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.
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.
RunRequest: Unified request for starting or resuming a run.
RuntimeRegistryUpdate
SerializableRegistryDiagnostic
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.
Phase: Lifecycle phase within an agent run.
ProviderRemovalPolicy
RecordSource: Who wrote this record into ConfigStore.
RegistryDiagnostic
RegistryDiagnosticSeverity
RegistryUpdateError
RuntimeError: Runtime-specific errors that wrap StateError and add variants for agent resolution and run management.
StateError
UnknownFieldPolicy: Unknown-field behavior for a serializable config surface.
UnknownKeyPolicy

Constants§

AGENT_SPEC_PATCH_UNKNOWN_FIELD_POLICY
AGENT_SPEC_UNKNOWN_FIELD_POLICY: AgentSpec and AgentSpecPatch reject unknown fields.
DEFAULT_MAX_PHASE_ROUNDS
MODEL_BINDING_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.

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.
EffectSpec
PhaseHook
Plugin
PluginConfigKey: Typed plugin configuration key.
ScheduledActionSpec
StateKey
ToolGateHook
TypedEffectHandler
TypedScheduledActionHandler
TypedTool: A strongly-typed tool trait that derives its descriptor schema from Args.

Functions§

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.
preview_provider_removal
rebuild_agent_model_provider_registries
sanitize_for_llm: Sanitize a JSON Schema value in-place to be LLM-friendly.
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_binding_spec: Validate and decode a ModelBindingSpec for config write surfaces.
validate_provider_spec: Validate and decode a ProviderSpec for config write surfaces.

Crate awaken

Crate awaken Copy item path

§Quick start

§Module layout

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Crate awaken