RFC: Opt-in policy hook for AgentKit action execution (budget / risk providers like Cycles)

[amavashev]

Language Implementation

• Python
• TypeScript

Feature Type

• Action Provider Template
• Wallet Provider Template
• Framework Extension
• Core Requirements
• Other

🚀 The feature, motivation and pitch

I’d like to propose an opt-in policy hook around AgentKit action execution so users can plug in pre-execution spend/risk controls without changing default behavior.

Problem

AgentKit is one of the clearest examples of an agent framework where action authority is the product: once an agent has wallet + action access, a bad loop or bad orchestration path can create real onchain spend or unwanted side effects quickly.

Today, users can compose their own controls outside AgentKit, but there does not appear to be a first-class, provider-agnostic hook for:

• pre-execution allow / deny decisions
• per-wallet / per-user / per-run / per-day budget checks
• optional post-action settlement / release
• structured policy/audit metadata around why an action was allowed or denied

That makes these controls ad hoc and harder to standardize across AgentKit integrations.

Proposal

Add an optional policy interface that wraps action execution.

High-level shape:

1. Before an AgentKit action executes, AgentKit calls a policy provider with action context.
2. The provider returns a decision such as allow or deny (optionally with metadata / reason).
3. If the action executes successfully, AgentKit can call an optional post-execution hook.
4. If the action fails or is aborted, AgentKit can call an optional failure/release hook.

This would let AgentKit users plug in:

• budget providers
• risk engines
• approval gates
• internal governance systems
• audit / observability enrichers

without changing AgentKit’s default behavior for users who do not enable it.

Desired properties

• Fully opt-in
• No default behavior change
• Provider-agnostic interface (not Cycles-specific)
• Small surface area
• Works with both wallet-backed and non-wallet actions
• Usable across TypeScript and Python implementations

Example shape

Pseudo-interface only to make the idea concrete:

TypeScript

type PolicyDecision =
  | { decision: "allow"; metadata?: Record<string, string> }
  | { decision: "deny"; reason: string; metadata?: Record<string, string> };

interface ActionPolicyProvider {
  beforeAction(context: {
    actionName: string;
    walletAddress?: string;
    network?: string;
    args: unknown;
    userId?: string;
    sessionId?: string;
    runId?: string;
  }): Promise<PolicyDecision>;

  afterAction?(context: unknown, result: unknown): Promise<void>;
  onActionError?(context: unknown, error: unknown): Promise<void>;
}

Python

class ActionPolicyProvider(Protocol):
    async def before_action(self, context) -> PolicyDecision: ...
    async def after_action(self, context, result) -> None: ...
    async def on_action_error(self, context, error) -> None: ...

Why this seems useful for AgentKit

This would let AgentKit support patterns like:

max onchain spend per wallet per day
max actions per user / agent / run
denylist/allowlist for high-risk actions
environment-aware policies (prod vs test)
externalized audit/governance

without baking any one policy model into core.

Concrete integration I’d be happy to contribute

I maintain Cycles (Apache 2.0), a reserve/commit runtime budget layer for agent execution. I’d be happy to contribute:

an initial policy hook abstraction
a minimal opt-in implementation path
docs/examples
a Cycles adapter as one example provider

But the main ask here is the core hook itself, not adoption of any one vendor/project.

Suggested rollout

Phase 1:

define minimal policy interface
wire it into action execution path
no behavior change unless configured

Phase 2:

docs + examples
one reference implementation / adapter

If this direction seems reasonable, I’m happy to open a draft PR after aligning on API shape here.

Alternatives

---

Copy/paste for “Alternatives”

Alternatives considered:

1. **Leave this entirely to application code**
   - Works, but every team reinvents the same wrapper differently.
   - Harder to standardize around action governance and audit semantics.

2. **Build this only in framework-specific extensions**
   - Useful, but misses the core AgentKit action surface.
   - Would fragment behavior across integrations.

3. **Bake one concrete budget/risk model directly into AgentKit**
   - I do not think this is the right approach.
   - A provider/hook abstraction seems cleaner and more future-proof than embedding one opinionated policy engine in core.

### Additional context

_No response_

[amavashev]

Happy to draft a minimal implementation behind a flag/config so this can be evaluated with zero default behavior change. If helpful, I can also sketch the exact insertion points in the current action execution path.