Agent Golden Path

1. Install the agent interfaces

# Python 3.10+ SDK: init, doctor, UserOperation helpers
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "aegis-smart-accounts>=0.5.0"
aegis --help

# Verify and install the operator-provided package
aegis handoff install /path/to/agent-aegis-handoff.zip \
  --destination ~/.aegis/handoffs/agent
aegis handoff check ~/.aegis/handoffs/agent

# MCP: live context, holdings, permission/quota, preflight, receipts, errors
npx -y @project-aegis/mcp-server

The SDK is the CLI and Python execution helper layer. The MCP server is the diagnostic/tool layer; it does not hold the signer key or submit transactions. Register it with an MCP client rather than running it as a standalone command. Use the published Aegis skill for the detailed ABI, DeFi, x402, and chain-specific reference. A local signer file outside Git at mode 0600 is acceptable, while a secret manager or external signer is stronger. Keep credentials out of prompts and the SDK init state.

2. Load the verified runtime handoff

Read START-HERE.md and the public manifest, then pass the installer-reported descriptor path to a secure subprocess. Never print files under secrets/, read a private key into the conversation, or substitute the owner key. The manifest binds the chain, smart account, exact primary permission, signer, and every included file hash. Backend diagnostics may use only an optional expiring, agent-bound runtime key.

AEGIS_CHAIN_ID=11155111
AEGIS_RUNTIME_SECRET_FILE=./secrets/runtime-secrets.env
AEGIS_SMART_ACCOUNT_ADDRESS=0x...
AEGIS_AGENT_UUID=...
AEGIS_ONCHAIN_AGENT_ID=0x...
AEGIS_PERMISSION_ID=0x...
AEGIS_BOT_ADDRESS=0x...
AEGIS_ROUTE_MODE=direct
AEGIS_SIGNER_SECRET_FILE=./secrets/agent.signer.env
AEGIS_ENTRYPOINT_ADDRESS=0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789
# RPC and optional aegisrt_ key are loaded from the separate runtime-secret file.
# A bundler-mode descriptor also references AEGIS_BUNDLER_URL there.

3. Confirm the execution route and gas destination

Policy-ready does not mean execution-ready. Keep the three native-balance buckets separate:

• Smart-account balance: policy-protected spendable value; it may cover first-operation bundler prefund.
• Bot signer EOA balance: ordinary network fees on the direct route; keep this outside-policy balance small.
• EntryPoint deposit: the standing ERC-4337 gas reserve used only by the bundler route.

4. Diagnose before building

aegis handoff check ~/.aegis/handoffs/agent --json

aegis runtime check --env-file ~/.aegis/handoffs/agent/agent.runtime.env --json

# Trusted control-plane diagnosis remains available separately:
aegis doctor --agent-id AGENT_UUID --permission-id PERMISSION_UUID --asset native

aegis_doctor {
  "agent_id": "AGENT_UUID",
  "permission_id": "PERMISSION_UUID",
  "asset": "native"
}

Runtime check verifies the redacted descriptor, signer, live immutable account bindings, exact permission, RPC, selected route, and its correct funding bucket without submitting. Direct mode probes the account capability and signer gas; bundler mode checks EntryPoint and bundler methods. The separate Doctor command resolves account.enforcer() and that enforcer's registries for authenticated control-plane diagnosis. Use the manifest's exact primary permission; never choose the newest one. If a legacy handoff is ambiguous, stop and ask the operator to select a primary permission and generate a new package. A held token is not automatically covered by a permission.

5. Build and preflight the exact action

Use the permission ID from diagnosis and prefix every policy-only inner call with 0xae915909 || permissionId || actualCalldata. Run aegis_preflight_transaction, then let the SDK perform the route-specific dry run: direct requires the account capability and uses eth_call plus eth_estimateGas; bundler mode follows build, sign, UserOperation estimate, re-sign, then explicit submit. Show the operator the preflight result and wait for approval before broadcasting.

For the standard CLI path, put the unprefixed target calldata in a calls-form action request and run aegis action run. The SDK applies the prefix and account wrapper, reads the route's correct nonce and fees, and performs the no-broadcast simulation automatically. Supplying a raw UserOperation is an advanced bundler-only path.

Use the same request and descriptor for dry run and submission; do not rebuild it by hand between review and execution:

# No broadcast: capability, policy, signer, route, nonce, gas, and funding checks
aegis action run \
  --env-file ~/.aegis/handoffs/agent/agent.runtime.env \
  --request-file ./approved-action.json

# Only after reviewing the exact dry-run output and receiving approval
aegis action run \
  --env-file ~/.aegis/handoffs/agent/agent.runtime.env \
  --request-file ./approved-action.json \
  --execute

build_execute wraps calldata; it does not create Uniswap, Aerodrome, or other DEX calldata. Encode the target call against the exact router ABI, then run target-level estimation and Aegis preflight before submission.

6. Submit and verify

After approval, submit through the selected route. Direct mode returns the ordinary EVM transaction hash. Bundler mode returns a UserOperation hash; read the nested receipt.transactionHash from eth_getUserOperationReceipt. If direct submission is ambiguous, inspect its deterministic transaction hash before any retry. In either mode, verify receipt success, usage on the resolved enforcer, and the expected indexed audit event.

Optional: provision through the SDK

If the operator explicitly asks for an SDK/API-first setup instead of dashboard setup, run the resumable initializer with public owner and signer addresses:

aegis init   --name my-agent   --owner 0xOWNER   --signer 0xBOT_SIGNER   --chain-id 11155111   --policy-file ./minimal-sepolia-policy.json

The initializer records only public state in ~/.aegis/init-state.json; it does not create signer material. Prepare an aegis.handoff.v1 package or equivalent secure files after provisioning, then return to steps 2–6.