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
• ✅ Use the v2.0 value + valueDecimals system
• ✅ 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:

{
  "value": "2",
  "valueDecimals": 0,
  "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

{
  "value": "2",
  "valueDecimals": 0,
  "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:

{
  "value": "3",
  "valueDecimals": 0,
  "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.",
  "tag1": "needs-improvement",
  "tag2": "fast-response"
}

Feedback Type Guide (5-Star Scale)

Positive Feedback (4-5 Stars)

When to Use:

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

Example:

{
  "agentRegistry": "eip155:11155111:0x8004...",
  "agentId": 123,
  "clientAddress": "eip155:11155111:0x742d...",
  "createdAt": "2025-12-20T10:00:00Z",
  "value": "5",
  "valueDecimals": 0,
  "reasoning": "Excellent blockchain analytics. Analyzed 1000+ transactions in under 5 seconds. Detected 3 suspicious patterns I missed manually. Highly recommend.",
  "tag1": "fast",
  "tag2": "accurate"
}

Mixed Feedback (2-3 Stars)

When to Use:

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

Example:

{
  "value": "3",
  "valueDecimals": 0,
  "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.",
  "tag1": "good-ui",
  "tag2": "expensive",
  "attachments": [
    {
      "name": "Feature Comparison",
      "uri": "ipfs://bafkrei...",
      "mimeType": "text/markdown",
      "description": "Comparison with similar agents showing price/feature gaps"
    }
  ]
}

Negative Feedback (0-1 Stars or Negative)

When to Use:

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

Example:

{
  "value": "-1",
  "valueDecimals": 0,
  "reasoning": "Agent claimed '99% uptime' but was offline for 6 hours during critical market event. No refund offered despite x402 payment. Support unresponsive.",
  "tag1": "unreliable",
  "tag2": "dispute",
  "attachments": [
    {
      "name": "Downtime Logs",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/json",
      "description": "Ping logs showing 6-hour offline period"
    },
    {
      "name": "Payment Receipt",
      "uri": "ipfs://bafkrei...",
      "mimeType": "application/json",
      "description": "x402 payment proof"
    }
  ]
}

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

Scoring Guidelines (v2.0)

Using the standard 5-Star Rating pattern (valueDecimals = 0):

Value	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	Very Poor	Completely non-functional
<0	Dispute / Scam	Fraud, malicious behavior, or dispute

Tips:

• Use valueDecimals: 1 for half-stars (e.g., 45 = 4.5 stars).
• Use tag1 to define the metric type if not using a general rating (e.g., tag1: "uptime").

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

{
  "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

{
  "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

{
  "value": "2",
  "valueDecimals": 0,
  "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)

# 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:

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

Method 2: Inline JSON (Small Data)

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

{
  "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)

{
  "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:

{
  "value": "5",
  "valueDecimals": 0,
  "reasoning": "Excellent A2A collaboration. Agent responded within SLA and provided structured data.",
  "skill": "analytical_skills/data_analysis/blockchain_analysis",
  "domain": "technology/blockchain",
  "context": "Analyzed blockchain transaction patterns",
  "tag1": "a2a-compatible",
  "tag2": "fast-response"
}

MCP Protocol Feedback

For MCP tool/prompt feedback:

{
  "value": "4",
  "valueDecimals": 0,
  "reasoning": "MCP tools work well. analyze_wallet tool is accurate.",
  "capability": "tools",
  "name": "analyze_wallet",
  "tag1": "mcp",
  "tag2": "tools"
}

x402 Payment Feedback

When using x402 payment protocol:

{
  "value": "5",
  "valueDecimals": 0,
  "reasoning": "Fair pricing via x402. Paid 0.01 ETH for premium analysis. Worth it.",
  "proofOfPayment": {
    "protocol": "x402",
    "amount": "10000000000000000",
    "currency": "ETH",
    "txHash": "0xabc123...",
    "chainId": 1,
    "timestamp": "2025-12-20T10:00:00Z"
  },
  "tag1": "good-value",
  "tag2": "x402-compatible"
}

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:

// ❌ 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 Templates

Template 1: Service Quality Feedback

{
  "agentRegistry": "eip155:11155111:0x...",
  "agentId": 123,
  "clientAddress": "eip155:11155111:0x...",
  "createdAt": "2025-12-20T10:00:00Z",
  "value": "4",
  "valueDecimals": 0,
  "reasoning": "[What you experienced, specific examples, overall impression]",
  "tag1": "tag1",
  "tag2": "tag2"
}

Template 2: Detailed Technical Feedback

{
  "agentRegistry": "eip155:11155111:0x...",
  "agentId": 123,
  "clientAddress": "eip155:11155111:0x...",
  "createdAt": "2025-12-20T10:00:00Z",
  "value": "3",
  "valueDecimals": 0,
  "reasoning": "[Detailed technical analysis]",
  "tag1": "performance",
  "tag2": "accuracy",
  "attachments": [
    {
      "name": "Benchmark Results",
      "uri": "ipfs://...",
      "mimeType": "application/json",
      "description": "Performance test results (1000 requests over 24 hours)"
    }
  ]
}

Template 3: Payment/Value Feedback

{
  "value": "5",
  "valueDecimals": 0,
  "reasoning": "Excellent value for money. Premium tier justifies cost.",
  "proofOfPayment": {
    "protocol": "x402",
    "amount": "10000000000000000",
    "currency": "ETH",
    "txHash": "0x..."
  },
  "tag1": "good-value",
  "tag2": "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: tag1: "agent", tag2: "feedback"

✅ Good: tag1: "slow-response", tag2: "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 tag1: "test" to distinguish from production use.

Resources

• Feedback Standard
• Validation Best Practices
• Value Decimals Patterns