Embed an Agent in a Rust application

Use this page after the checked examples run locally and the next task is to embed the Runtime in an application. It does not repeat their full source. Keep those examples as the executable baseline while replacing one boundary at a time.

Outcome

Your application will assemble one Runtime, compile or load one ExecutableAgentSnapshot, create one RuntimeRunContext, and read the terminal RunState plus committed output.

Prerequisites

• Create your first Agent configuration and Run your first Tool pass unchanged;
• the application has selected its model, Tool, permission, and persistence implementations;
• provider credentials are resolved by the application or Awaken Agents service, not read by the neutral Runtime.

1. Keep three lifetimes separate

Do not synchronize copies of the same value across these owners. Resolve a setting once, then pass it to the boundary whose lifetime matches it.

2. Choose the Agent publication path

• Use AgentConfig plus compile_resolved when the application authors config and needs a derived fingerprint. Follow hello_agent.rs.
• Use ExecutableAgentSnapshot::builder when the application already owns resolved, executable values. Follow direct_runtime.rs.

Both paths produce the same snapshot contract before Runtime::run. Choose one; do not compile an AgentConfig and then rebuild its snapshot by hand.

3. Replace process ports one at a time

Start with the checked local model double. Replace only the port needed by the application:

1. bind an explicitly configured LlmExecutor;
2. add typed Tools through Implement a typed Tool;
3. add one PermissionGate for every Tool execution path;
4. add Plugins or delegation only when the Agent requires them.

Run the baseline test after each replacement. This keeps a provider error, Tool contract error, and permission decision distinguishable.

4. Choose persistence for the attempt

RuntimeRunContext::new() permits an ephemeral run. Add a CommitCoordinator when the application needs a durable transcript or state, and add the matching read port when later runs must continue committed history. Use an awaken-store-* backend for persistence across process restarts.

Absence of a commit coordinator is not a Runtime fault. It is an explicit ephemeral choice. Do not tell maintainers to repair it unless the application requires durable output and failed to supply the port.

5. Run and handle the terminal result

Call Runtime::run for a fresh single-shot thread. Use the stable-thread start_run and resume path, or run_to_completion, when approval can place a run in Awaiting.

flowchart LR
  start[Input, immutable snapshot, attempt ports] --> model[Model request]
  model -->|Text| staged[Staged messages, state, and facts]
  model -->|ToolCall| gate[Permission]
  gate --> execution[Execution]
  execution --> staged
  staged --> commit[Step commit]
  commit --> terminal[NaturalEnd, Awaiting, Cancelled, MaxSteps, or Error]

Awaiting is a state to resume, not a failure to restart. Tool invocation errors become model-visible results. Consecutive inference failures are retried inside the loop up to the Runtime threshold. Act only when the returned terminal result or surfaced configuration error requires a change outside that recovery.

6. Verify

For the application path, test at least these outcomes:

Attach the cause, expected effect, and covered rule to each test. Use one decision table in test comments rather than a separate test-design document.

Next steps

• Persist history: Use File Store or Use Postgres Store.
• Add approval: Tool permission HITL.
• Expose the application through the owning service plane: Awaken Agents.