Feedback Best Practices

Description

Practical guide for creating effective agent feedback

Audience: Agent users, developers, validators

Overview

This guide provides best practices for creating high-quality feedback on ERC-8004 agents, helping build trust and improve the ecosystem.

What You'll Learn:

✅ Write clear, actionable feedback
✅ Provide effective evidence using attachments
✅ Choose appropriate feedback types
✅ Handle privacy and sensitive data
✅ Use protocol-specific fields (A2A, MCP, x402)

Feedback Principles

1. Be Specific and Actionable

❌ Bad: "Agent doesn't work"

✅ Good:

json

{
  "feedbackType": "negative",
  "score": 2,
  "reasoning": "Agent failed to analyze wallet 0x1234... Transaction parsing error at block 18500000. Expected JSON response but received HTML error page.",
  "reproducible": true
}

Why: Specific feedback helps agent developers identify and fix issues.

2. Provide Evidence

❌ Bad: Trust me, it's broken

✅ Good: Include screenshots, logs, or API responses

json

{
  "feedbackType": "negative",
  "score": 2,
  "reasoning": "Agent returned error when analyzing wallet",
  "attachments": [
    {
      "name": "Error Screenshot",
      "uri": "ipfs://bafkreiabc...",
      "mimeType": "image/png",
      "description": "Screenshot showing '500 Internal Server Error' at 2025-12-20 14:30 UTC"
    },
    {
      "name": "Error Logs",
      "uri": "ipfs://bafkreixyz...",
      "mimeType": "application/json",
      "description": "Full API response logs with stack trace"
    }
  ]
}

3. Be Fair and Constructive

❌ Bad: "This agent is garbage"

✅ Good:

json

{
  "feedbackType": "mixed",
  "score": 3,
  "reasoning": "Agent successfully analyzed 80% of test cases (8/10). Failed on complex multi-sig transactions. Response time was excellent (~2s average). Recommend adding multi-sig support.",
  "tags": ["needs-improvement", "fast-response"]
}

Feedback Type Guide

Positive Feedback (score: 4-5)

When to Use:

Agent performed as expected
Results were accurate
Response time was acceptable
Good user experience

Example:

json

{
  "agentRegistry": "eip155:11155111:0x8004a6090Cd10A7288092483047B097295Fb8847",
  "agentId": 123,
  "clientAddress": "eip155:11155111:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
  "createdAt": "2025-12-20T10:00:00Z",
  "feedbackType": "positive",
  "score": 5,
  "reasoning": "Excellent blockchain analytics. Analyzed 1000+ transactions in under 5 seconds. Detected 3 suspicious patterns I missed manually. Highly recommend.",
  "tags": ["fast", "accurate", "recommended"]
}

Mixed Feedback (score: 2-4)

When to Use:

Agent works but has limitations
Some features good, others need improvement
Acceptable but not great

Example:

json

{
  "feedbackType": "mixed",
  "score": 3,
  "reasoning": "Good for simple queries, but struggles with complex analysis. Free tier works well. Premium features overpriced at 0.1 ETH per report. UI is intuitive.",
  "tags": ["good-ui", "expensive", "limited-features"],
  "attachments": [
    {
      "name": "Feature Comparison",
      "uri": "ipfs://bafkrei...",
      "mimeType": "text/markdown",
      "description": "Comparison with similar agents showing price/feature gaps"
    }
  ]
}

Negative Feedback (score: 0-2)

When to Use:

Agent failed to deliver
Critical bugs or errors
Safety/security concerns
Misleading claims

Example:

json

{
  "feedbackType": "negative",
  "score": 1,
  "reasoning": "Agent claimed '99% uptime' but was offline for 6 hours during critical market event. No refund offered despite x402 payment. Support unresponsive.",
  "tags": ["unreliable", "poor-support", "false-advertising"],
  "attachments": [
    {
      "name": "Downtime Logs",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/json",
      "description": "Ping logs showing 6-hour offline period (2025-12-15 08:00-14:00 UTC)"
    },
    {
      "name": "Payment Receipt",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/json",
      "description": "x402 payment proof (0.05 ETH for 24h service)"
    }
  ]
}

Important: Always provide evidence for negative feedback to prevent abuse.

Scoring Guidelines

Score	Meaning	When to Use
5	Outstanding	Exceeded expectations, highly recommend
4	Good	Met expectations, would use again
3	Acceptable	Works but has issues, neutral recommendation
2	Below Average	Significant problems, not recommended
1	Poor	Failed to deliver, do not use
0	Completely Failed	Agent non-functional or malicious

Tips:

Reserve 5★ for truly exceptional experiences
Use 3★ as baseline for "works as advertised"
Only use 0★ for serious issues (scams, malware, data breaches)

Attachment Pattern Best Practices

Supported File Types

Type	MIME Type	Use Case	Example
PDF	`application/pdf`	Audit reports, documentation	Security audit report
Images	`image/png`, `image/jpeg`	Screenshots, diagrams	Error screenshots
JSON	`application/json`	API responses, test results	Agent API response logs
Text	`text/plain`, `text/markdown`	Logs, notes	Detailed test notes
CSV	`text/csv`	Benchmark data	Performance benchmarks
Video	`video/mp4`, `video/webm`	Screen recordings	Demo of bug reproduction
ZIP	`application/zip`	Multiple files	Complete test suite results

Attachment Examples

Example 1: Security Audit Report

json

{
  "reasoning": "Passed third-party security audit with 0 critical findings",
  "attachments": [
    {
      "name": "Security Audit Report",
      "uri": "ipfs://bafkreifjv...",
      "mimeType": "application/pdf",
      "size": 2048000,
      "description": "Automated scan using Slither v0.9.6 + manual review by certified auditor. Scanned 5 smart contracts and 2 API endpoints. Report dated 2025-12-15.",
      "uploadedAt": "2025-12-16T10:00:00Z"
    }
  ]
}

Example 2: Performance Benchmarks

json

{
  "reasoning": "Tested performance under load. Results show excellent scalability.",
  "attachments": [
    {
      "name": "Benchmark Results",
      "uri": "ipfs://bafkreiabc...",
      "mimeType": "text/csv",
      "size": 50000,
      "description": "1000 API calls on Sepolia testnet. Average response time: 1.2s. 99.9% uptime over 7 days. Test environment: AWS t3.medium instance.",
      "uploadedAt": "2025-12-16T12:00:00Z"
    },
    {
      "name": "Load Test Graph",
      "uri": "ipfs://bafkreixyz...",
      "mimeType": "image/png",
      "size": 150000,
      "description": "Response time vs concurrent requests graph. Shows linear scaling up to 100 concurrent users."
    }
  ]
}

Example 3: Bug Reproduction

json

{
  "feedbackType": "negative",
  "score": 2,
  "reasoning": "Agent crashes when processing ERC-4337 account abstraction wallets",
  "attachments": [
    {
      "name": "Bug Reproduction Steps",
      "uri": "ipfs://bafkrei...",
      "mimeType": "text/markdown",
      "size": 5000,
      "description": "Step-by-step reproduction guide with test wallet address and transaction hash"
    },
    {
      "name": "Error Video",
      "uri": "ipfs://bafkrei...",
      "mimeType": "video/mp4",
      "size": 5000000,
      "description": "Screen recording showing agent crash when analyzing wallet 0x1234... at timestamp 00:42"
    },
    {
      "name": "API Logs",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/json",
      "size": 20000,
      "description": "Complete API request/response logs showing 500 error with stack trace"
    }
  ]
}

Attachment Upload Methods

Method 1: IPFS Upload (Recommended)

bash

# Using IPFS CLI
ipfs add security-audit.pdf
# Returns: added QmXXX... security-audit.pdf

# Using Pinata API
curl -X POST "https://api.pinata.cloud/pinning/pinFileToIPFS" \
  -H "Authorization: Bearer YOUR_JWT" \
  -F "file=@security-audit.pdf"

Attachment:

json

{
  "name": "Security Audit Report",
  "uri": "ipfs://QmXXX...",
  "mimeType": "application/pdf"
}

Method 2: Inline JSON (Small Data)

For small datasets (<100KB), embed directly:

json

{
  "reasoning": "Benchmark results attached",
  "attachments": [
    {
      "name": "Performance Metrics",
      "uri": "data:application/json;base64,eyJhdmdSZXNwb25zZVRpbWUiOjEuMiwicDk5IjoyLjV9",
      "mimeType": "application/json",
      "description": "Key metrics: avg 1.2s, p99 2.5s"
    }
  ]
}

Method 3: HTTPS URL (Centralized but Fast)

json

{
  "name": "Test Results Dashboard",
  "uri": "https://example.com/test-results/agent-123-2025-12-20.html",
  "mimeType": "text/html",
  "description": "Interactive dashboard with real-time test results (requires login)"
}

⚠️ Caution: HTTPS URLs can change or disappear. Prefer IPFS for permanence.

Protocol-Specific Fields

A2A Protocol Feedback

When providing feedback after A2A (Agent-to-Agent) interactions:

json

{
  "feedbackType": "positive",
  "score": 5,
  "reasoning": "Excellent A2A collaboration. Agent responded within SLA and provided structured data.",
  "a2aInteraction": {
    "requestId": "req-uuid-1234",
    "responseTime": 1.8,
    "skillsUsed": ["analytical_skills/data_analysis/blockchain_analysis"],
    "protocol": "A2A v0.3.0"
  },
  "tags": ["a2a-compatible", "fast-response"]
}

MCP Protocol Feedback

For MCP tool/prompt feedback:

json

{
  "feedbackType": "positive",
  "score": 4,
  "reasoning": "MCP tools work well. analyze_wallet tool is accurate. summarize_trends prompt is helpful.",
  "mcpFeedback": {
    "toolsUsed": ["analyze_wallet", "detect_anomalies"],
    "promptsUsed": ["What are the risks?"],
    "serverVersion": "2025-06-18",
    "issues": ["analyze_wallet sometimes times out on large wallets"]
  }
}

x402 Payment Feedback

When using x402 payment protocol:

json

{
  "feedbackType": "positive",
  "score": 5,
  "reasoning": "Fair pricing via x402. Paid 0.01 ETH for premium analysis. Worth it.",
  "paymentProof": {
    "protocol": "x402",
    "amount": "10000000000000000",
    "currency": "ETH",
    "transactionHash": "0xabc123...",
    "chainId": 1,
    "timestamp": "2025-12-20T10:00:00Z"
  },
  "costEffectiveness": "excellent"
}

Privacy and Security

DO Include

✅ General performance metrics
✅ Anonymized test data
✅ Public blockchain addresses (if relevant)
✅ Error messages (sanitized)
✅ Public API endpoints

DO NOT Include

❌ Private keys or seed phrases
❌ API keys or access tokens
❌ Personal identifiable information (PII)
❌ Confidential business data
❌ Internal system details (if security-sensitive)

Example of Sanitization:

json

// ❌ BAD
{
  "reasoning": "API key sk-1234abcd exposed in logs"
}

// ✅ GOOD
{
  "reasoning": "API credentials exposed in error response (redacted for security)",
  "attachments": [
    {
      "name": "Sanitized Logs",
      "uri": "ipfs://...",
      "description": "Error logs with sensitive data redacted"
    }
  ]
}

Feedback Authorization

Anonymous Feedback

json

{
  "clientAddress": "eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
  "feedbackType": "positive",
  "score": 5,
  "reasoning": "Great agent!",
  "authorization": {
    "signature": "0xabc123...",
    "message": "I approve this feedback for agent 123 on 2025-12-20",
    "signer": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"
  }
}

Validator-Endorsed Feedback

For feedback from trusted validators:

json

{
  "clientAddress": "eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
  "feedbackType": "positive",
  "score": 5,
  "reasoning": "Agent passed comprehensive security validation",
  "validatorEndorsement": {
    "validatorAddress": "eip155:1:0x1234...",
    "validatorTier": "platform",
    "endorsementType": "security-audit",
    "signature": "0xdef456..."
  },
  "attachments": [
    {
      "name": "Validator Report",
      "uri": "ipfs://...",
      "mimeType": "application/pdf"
    }
  ]
}

Feedback Templates

Template 1: Service Quality Feedback

json

{
  "agentRegistry": "eip155:11155111:0x...",
  "agentId": 123,
  "clientAddress": "eip155:11155111:0x...",
  "createdAt": "2025-12-20T10:00:00Z",
  "feedbackType": "positive|mixed|negative",
  "score": 4,
  "reasoning": "[What you experienced, specific examples, overall impression]",
  "tags": ["tag1", "tag2"],
  "reproducible": true|false
}

Template 2: Detailed Technical Feedback

json

{
  "agentRegistry": "eip155:11155111:0x...",
  "agentId": 123,
  "clientAddress": "eip155:11155111:0x...",
  "createdAt": "2025-12-20T10:00:00Z",
  "feedbackType": "mixed",
  "score": 3,
  "reasoning": "[Detailed technical analysis]",
  "tags": ["performance", "accuracy"],
  "attachments": [
    {
      "name": "Benchmark Results",
      "uri": "ipfs://...",
      "mimeType": "application/json",
      "description": "Performance test results (1000 requests over 24 hours)"
    }
  ],
  "reproducible": true,
  "testEnvironment": {
    "network": "sepolia",
    "toolsUsed": ["postman", "k6"],
    "duration": "24h"
  }
}

Template 3: Payment/Value Feedback

json

{
  "feedbackType": "positive",
  "score": 5,
  "reasoning": "Excellent value for money. Premium tier justifies cost.",
  "paymentProof": {
    "protocol": "x402",
    "amount": "10000000000000000",
    "currency": "ETH",
    "transactionHash": "0x..."
  },
  "costEffectiveness": "excellent",
  "tags": ["good-value", "x402-compatible"]
}

Common Mistakes to Avoid

Mistake 1: Vague Feedback

❌ Bad: "Doesn't work"

✅ Good: "analyze_wallet tool returns 500 error for wallets with >1000 transactions. Tested with 0x1234..."

Mistake 2: No Evidence for Claims

❌ Bad: "Agent is a scam, stole my data"

✅ Good: Include proof (logs, transaction hashes, screenshots)

Mistake 3: Emotional/Abusive Language

❌ Bad: "This garbage agent is a complete waste of time run by idiots"

✅ Good: "Agent did not meet advertised SLA (99% uptime). Measured 92% uptime over 7 days. Request refund."

Mistake 4: Irrelevant Tags

❌ Bad: ["agent", "feedback", "blockchain", "ai", "test"]

✅ Good: ["slow-response", "accurate-results", "expensive"]

FAQ

Q: Should I leave feedback after every interaction?
A: No, prioritize feedback for:

Exceptional experiences (very good or very bad)
First-time use of an agent
After major updates
When explicitly requested by agent owner

Q: Can I update feedback later?
A: Depends on implementation. 8004scan supports feedback updates via new transactions.

Q: What if agent owner disputes my feedback?
A: Provide evidence via attachments. On-chain feedback is immutable, but reputation systems may weight evidence.

Q: Should I give feedback for test interactions?
A: Yes, but use tags like ["test", "dev-environment"] to distinguish from production use.

Resources

Feedback Standard
Validation Best Practices
8004scan Feedback UI (coming soon)

Feedback Best Practices

Description ​

Overview ​

Feedback Principles ​

1. Be Specific and Actionable ​

2. Provide Evidence ​

3. Be Fair and Constructive ​

Feedback Type Guide ​

Positive Feedback (score: 4-5) ​

Mixed Feedback (score: 2-4) ​

Negative Feedback (score: 0-2) ​

Scoring Guidelines ​

Attachment Pattern Best Practices ​

Supported File Types ​

Attachment Examples ​

Example 1: Security Audit Report ​

Example 2: Performance Benchmarks ​

Example 3: Bug Reproduction ​

Attachment Upload Methods ​

Method 1: IPFS Upload (Recommended) ​

Method 2: Inline JSON (Small Data) ​

Method 3: HTTPS URL (Centralized but Fast) ​

Protocol-Specific Fields ​

A2A Protocol Feedback ​

MCP Protocol Feedback ​

x402 Payment Feedback ​

Privacy and Security ​

DO Include ​

DO NOT Include ​

Feedback Authorization ​

Anonymous Feedback ​

Validator-Endorsed Feedback ​

Feedback Templates ​

Template 1: Service Quality Feedback ​

Template 2: Detailed Technical Feedback ​

Template 3: Payment/Value Feedback ​

Common Mistakes to Avoid ​

Mistake 1: Vague Feedback ​

Mistake 2: No Evidence for Claims ​

Mistake 3: Emotional/Abusive Language ​

Mistake 4: Irrelevant Tags ​

FAQ ​

Resources ​

Description

Overview

Feedback Principles

1. Be Specific and Actionable

2. Provide Evidence

3. Be Fair and Constructive

Feedback Type Guide

Positive Feedback (score: 4-5)

Mixed Feedback (score: 2-4)

Negative Feedback (score: 0-2)

Scoring Guidelines

Attachment Pattern Best Practices

Supported File Types

Attachment Examples

Example 1: Security Audit Report

Example 2: Performance Benchmarks

Example 3: Bug Reproduction

Attachment Upload Methods

Method 1: IPFS Upload (Recommended)

Method 2: Inline JSON (Small Data)

Method 3: HTTPS URL (Centralized but Fast)

Protocol-Specific Fields

A2A Protocol Feedback

MCP Protocol Feedback

x402 Payment Feedback

Privacy and Security

DO Include

DO NOT Include

Feedback Authorization

Anonymous Feedback

Validator-Endorsed Feedback

Feedback Templates

Template 1: Service Quality Feedback

Template 2: Detailed Technical Feedback

Template 3: Payment/Value Feedback

Common Mistakes to Avoid

Mistake 1: Vague Feedback

Mistake 2: No Evidence for Claims

Mistake 3: Emotional/Abusive Language

Mistake 4: Irrelevant Tags

FAQ

Resources