Search documentation
Browse Awaken Agents docs ›

On this page

Docs/Awaken Agentsv1.0.0-dev/Internal mechanisms/UnderstandDevelop Awaken Agents capabilities
Note·You're reading pre-release documentation (v1.0.0-dev). Interfaces and behavior may change before a stable release.

Internal mechanisms · Understand

Develop Awaken Agents capabilities

What this page covers

Choose the code-owned capability to add without creating a second execution, state, permission, or persistence path.

Use this path when an Agent needs a capability that must be implemented in Rust. Put actions, lifecycle constraints, provider adapters, and storage ports in code. Put behavior that should change without rebuilding the process in typed or managed configuration.

Start from the change

You need to changeContinue withKeep as the single owner
Agent instructions, model choice, Tool visibility, or limitsConfigure Agent behaviorAgent publication
Runtime assembly in an applicationEmbed an Agentapplication process
A model-requested actionImplement a typed ToolTool implementation plus derived descriptor
Lifecycle context, filtering, or policyAdd a PluginRuntime Plugin path
State scope, merge, replay, or persistenceState and storagestaged commands plus commit coordinator
A controlled child resultInvoke a sub-Agent from a ToolRun delegation service
Long work that outlives the turnStart background work from a Toolordinary durable Run and ingress
One Agent taking over the conversationUse Agent handoffactive-Agent transition at a step boundary
HTTP, protocols, Workers, Sandboxes, or managed credentialsAwaken Agentsservice and operations planes

If the requested behavior already has an owner in this table, extend that owner. Do not add a frontend dispatcher, prompt-only permission rule, private state store, or second retry loop.

Static structure

flowchart TB
  host[Application or Awaken Agents] --> publication[Agent publication]
  publication --> snapshot[ExecutableAgentSnapshot]
  host --> process[Process ports]
  process --> runtime[Runtime]
  host --> attempt[Attempt ports]
  attempt --> context[RuntimeRunContext]
  snapshot --> loop[Runtime execution loop]
  runtime --> loop
  context --> loop
  loop --> llm[LlmExecutor]
  loop --> gate[PermissionGate]
  gate --> executor[ToolExecutor]
  loop --> extensions[Plugins and delegation]
  loop --> commit[CommitCoordinator]

The Runtime depends on typed ports and immutable data. HTTP services, tenancy, placement, credentials, and deployment depend inward on that kernel; the kernel does not depend back on them.

Dynamic behavior

  1. The host resolves one immutable snapshot and the ports for one attempt.
  2. The Runtime asks the model for the next step.
  3. A Tool request passes through canonical id resolution and one permission gate before one executor runs it.
  4. Messages, state commands, facts, and disposition remain staged until the step commit succeeds.
  5. The run continues, waits on a resumable ticket, or returns one terminal RunState.

Tool errors are model-visible results. Waiting is resumed through the committed ticket. Inference has bounded in-loop retry. A previous commit remains the recovery point after an interrupted step. These are system behaviors, not a reason to add a troubleshooting section.

Decisions to make before coding

DecisionQuestionExisting owner
ConsequenceDoes the action read, write, execute, call a network, or use a credential?Tool plus permission policy
LifetimeIs the value process-wide, publication-pinned, attempt-only, or committed state?Runtime, snapshot, context, or coordinator
ConcurrencyCan two calls write the same key?MergePolicy at commit
RecoveryIs an external effect non-recoverable, replay-safe, or idempotent?Tool recovery contract
ContinuationDoes work return now, wait, run in the background, or transfer control?Tool result, awaiting, ordinary Run, or handoff

Record these choices in the implementation and its tests. Documentation should tell the next maintainer which owner to change and which observable result to verify.

Finish the change

Before considering a Runtime capability complete:

  1. run the smallest checked example that shares its boundary;
  2. derive a cause/effect table for success, rejection, waiting, retry, and terminal failure;
  3. keep that design in comments beside the corresponding tests;
  4. run the focused tests, then the owning crate tests;
  5. review the diff for a second owner or compatibility path.

Keep nearby