cloudwego / cloudwego/eino

[ADK] Provide standard tool policy and human approval middleware

Open
#996 9 comments 6 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
13k
Forks
1.1k
Avg merge
4h 6m
Merged PRs (30d)
41

Description

## Summary

I would like to propose a standard ADK middleware for tool policy control and human approval.

Eino already has tool execution abstractions, tool middleware, and interrupt/resume support. These are powerful primitives, but application developers still need to manually build a policy layer for deciding whether a tool call should be allowed, denied, rewritten, audited, or interrupted for human approval.

## Motivation

For production-grade agents, especially agents that can access filesystem, shell, browser, external APIs, or MCP tools, tool governance is a core requirement.

Common requirements include:

- Allow or deny tool calls based on tool name, arguments, agent, user, or runtime context
- Require human approval for high-risk tool calls
- Rewrite or sanitize tool arguments before execution
- Add audit logs for every tool call
- Return a safe tool result when a tool call is denied
- Use existing interrupt/resume mechanisms for approval workflows

Currently these can be implemented manually with middleware, but there is no standard reusable abstraction.

## Proposed Design

Add a reusable tool policy middleware in ADK.

A rough API could look like:

```go
type ToolPolicyDecision string

const (
ToolPolicyAllow ToolPolicyDecision = "allow"
ToolPolicyDeny ToolPolicyDecision = "deny"
ToolPolicyRequireApproval ToolPolicyDecision = "require_approval"
)

type ToolPolicyRequest struct {
AgentName string
ToolName string
Arguments string
RunPath []adk.RunStep
}

type ToolPolicyResult struct {
Decision ToolPolicyDecision
RewrittenArguments string
DenyMessage string
ApprovalInfo any
}

type ToolPolicy interface {
Decide(ctx context.Context, req *ToolPolicyRequest) (*ToolPolicyResult, error)
}
```

The middleware could wrap invokable, streamable, enhanced invokable, and enhanced streamable tool calls.

## Expected Behavior

- If decision is `allow`, execute the tool normally
- If decision is `deny`, return a configured tool result without executing the tool
- If decision is `require_approval`, interrupt execution and resume with approval/rejection data
- Optionally emit internal events for audit/debugging

## Expected Benefits

- Makes Eino safer for agents with powerful tools
- Provides a common pattern for human-in-the-loop tool approval
- Reduces duplicated policy logic in user applications
- Builds on existing Eino ADK primitives instead of introducing an application-specific system

## Related Context

This is a framework-level request, not a request for a specific sandbox implementation. Concrete sandbox backends or specific tool integrations can still live in `eino-ext` or user applications.

Contributor guide

Open the contributing guide

Research direction

Start by reading the existing ADK tool execution abstractions, tool middleware, and interrupt/resume support. Trace how invokable, streamable, enhanced invokable, and enhanced streamable tool calls are wrapped. Done means a reusable policy middleware supports allow, deny, argument rewriting, audit events, and human approval without introducing a specific sandbox implementation.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
ai, backend-api-design, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.