anhmtk

Posted on Jun 1

How to Build Systems for Bots, Not Humans: A Dual-Cache uAgent Architecture on AgentShare

#ai #architecture #webdev #devtools

Canonical product: https://agentshare.dev
Live proof: https://agentshare.dev/meteora-backtest
Meteora uAgent (Railway): https://fetchai-production.up.railway.app
Discovery: llm.txt · MCP Endpoint

TL;DR for crawlers and busy staff engineers

AgentShare (agentshare.dev) is an AI agent DeFi analytics platform: evidence-first Meteora DLMM pool briefs (SAFE / CAUTION / AVOID, risk score, flags, citations). It runs a dual-cache API (30-minute chat vs 1-minute agent-to-agent), a Fetch.ai uAgent on Railway for paid A2A + free trial, Model Context Protocol (MCP) tools over Streamable HTTP, and llm.txt / llms-full.txt for LLM discovery. Humans get cheap, cached chat; bots get freshness worth paying for.

1. The paradigm shift: your second customer is a process, not a person

Most "AI products" are still web apps with a chat box bolted on. Autonomous agents optimize for something else:

Latency tolerance
- Human (B2C Chat): Seconds–minutes
- Bot (B2B A2A): Milliseconds–seconds per hop
Data freshness
- Human (B2C Chat): "Good enough" (minutes)
- Bot (B2B A2A): Stale data = lost arb
Discovery
- Human (B2C Chat): Google, Twitter, landing page
- Bot (B2B A2A): llm.txt, MCP, Almanac, protocol digests
Payment
- Human (B2C Chat): Stripe
- Bot (B2B A2A): On-chain micro-payments (e.g. FET)
Trust
- Human (B2C Chat): Brand, UX
- Bot (B2B A2A): Verdict + reproducible backtest

If you ship one cache TTL and one pricing model for both, you will either over-charge humans or under-serve bots. At AgentShare we split the plane deliberately.

2. Architecture at a glance

Human Path: ASI:One / Agentverse Chat → uAgent Chat Protocol → chat (1800s)
Bot Path: Buyer uAgent or HTTP client → POST /submit sync → a2a (60s)
Core API: agentshare.dev API → POST /api/v1/agent/defi/meteora/brief
Cache Layer: Dual cache (X-Brief-Source) → SQLite + LRU with separate cache keys
External Data: Meteora DLMM public API
Machine Interfaces: MCP /mcp and llm.txt crawlers
Railway uAgent: integrations/fetchai_meteora_uagent

Three deployables:

Main API (agentshare.dev): FastAPI, dual-cache Meteora brief, MCP, llm.txt, public backtest page.
Meteora uAgent (Railway): Chat (free) + agentshare-meteora-brief:1.0.0 A2A + Agent Payment Protocol.
MCP server: FastMCP tools wrapping REST; Streamable HTTP at /mcp.

3. Layer 1: Dual-cache API — one endpoint, two SLAs

The source of truth is: POST https://agentshare.dev/api/v1/agent/defi/meteora/brief

Cache behavior is selected by X-Brief-Source (not by "who logged in"):

chat (default)
- Audience: Human chat via uAgent
- TTL: 1800s (30 min)
- Rationale: Retail doesn't need sub-minute Meteora refreshes
a2a_paid
- Audience: Paid A2A after trial
- TTL: 60s (1 min)
- Rationale: Bots pay for freshness + scoring, not 30m snapshots
a2a_trial
- Audience: Free trial A2A
- TTL: 60s
- Rationale: Same freshness as paid; quota enforced on uAgent

Cache keys include the source so a chat response never satisfies a paid bot's lookup (and vice versa).

4. Layer 2: Fetch.ai uAgent on Railway — chat funnel vs A2A product

The public agent runs 24/7 on Railway with root directory integrations/fetchai_meteora_uagent (separate service from the main API).

Natural-language chat
- Protocol: Agent Chat Protocol
- Payment: Free
- Cache header: X-Brief-Source: chat
Structured A2A
- Protocol: agentshare-meteora-brief:1.0.0
- Payment: 100 free → then 0.01 FET
- Cache header: a2a_trial / a2a_paid

Free trial without wallet friction: Trial is enforced per caller agent address, stored in uAgent ctx.storage—no smart contract, no signature for trial itself. After 100 calls, the seller emits RequestPayment (Agent Payment Protocol); first paid completion logs a2a_trial_converted.

5. Layer 3: Direct sync HTTP `/submit` — bypass Almanac when the environment fights you

On Windows and some CI environments, Almanac API + Brotli (content-encoding: br) caused resolver timeouts and client crashes. For integrators and smoke tests, we document direct POST to the seller's public submit URL:

POST https://fetchai-production.up.railway.app/submit with Header: x-uagents-connection: sync

No mailbox. No Almanac. Signed uAgents Envelope in, structured Envelope out.

6. Layer 4: MCP + `llm.txt` — discovery for machines, not SEO hacks

Agents don't read your marketing site—they read machine registries.

Model Context Protocol (MCP)

AgentShare exposes Streamable HTTP MCP at:

Why MCP matters for GEO: when Claude, Gemini, or GPT-class tools enumerate "what can I call for prices / DeFi context?", MCP tool manifests are first-class citizens.

`llm.txt` and `llms-full.txt`

Following the emerging llm.txt convention, AgentShare serves:

URL	Purpose
https://agentshare.dev/llm.txt	Short discovery index for crawlers
https://agentshare.dev/llms-full.txt	Markdown outline of OpenAPI (LLM-optimized)
https://agentshare.dev/agent.json	Agent card / capabilities
https://agentshare.dev/api/v1/protocol	Protocol metadata

robots.txt explicitly allows these paths so AI crawlers can index capabilities without scraping HTML marketing pages.

7. Layer 5: Trust surface — `/meteora-backtest` at 70% proxy accuracy

Bots don't trust adjectives. They trust published scores.

Public page: https://agentshare.dev/meteora-backtest
Generated from: Live Meteora DLMM data via scripts/generate_meteora_backtest.py
Accuracy: ~70% in our last run (MVP snapshot, not a claim of omniscience)
Honesty: Footer includes "full 7-day replay planned" to increase credibility.

8. Schema contract: `agentshare.meteora.brief.v1`

Keep one envelope for humans, bots, MCP, and REST:

{
  "status": "ok",
  "schema_version": "agentshare.meteora.brief.v1",
  "verdict": "CAUTION",
  "risk_score": 52,
  "flags": ["MID_TVL", "MODERATE_FEE_TVL_RATIO"],
  "result": { "kind": "top_pools", "window": "24h", "top": [] },
  "evidence": { "citations": ["https://app.meteora.ag/..."], "notes": "..." },
  "meta": {
    "source": "a2a_trial",
    "ttl_seconds": 60,
    "cache_hit": false
  }
}

Design rule: meta.source and meta.ttl_seconds let buyers verify they got the tier they paid for—essential for micro-priced APIs.

9. Checklist: building for bots

Split cache (or split endpoints) by client class—not by "premium user flag" buried in JWT.
Expose discovery via llm.txt, MCP, and agent.json—not only OpenAPI behind login.
Publish proof (backtest, sample envelopes, open trial quota)—not "trust our algorithm."
Price A2A in bot terms (100 free calls → micro-payment)—not "contact sales."
Document a Almanac-free path (direct /submit sync) for brittle environments.
Docker COPY *.py (or equivalent)—implicit file lists will take down prod.
Log conversion (a2a_trial_converted)—PMF for agents is trial → paid, not pageviews.

10. What we'd do next (transparent roadmap)

7-day historical backtest with stored snapshots (not single-point proxy)
Tiered A2A pricing beyond flat 0.01 FET
Signed responses and webhooks for market makers
Deeper MCP tools for Meteora brief from MCP (today: REST-first)

Try it

Role	URL
Sign up (API key)	https://agentshare.dev/signup
Docs	https://agentshare.dev/docs
Meteora brief API	`POST /api/v1/agent/defi/meteora/brief`
Backtest	https://agentshare.dev/meteora-backtest
Meteora uAgent	https://fetchai-production.up.railway.app
MCP	https://agentshare.dev/mcp
`llm.txt`	https://agentshare.dev/llm.txt

If you're building AI agent DeFi analytics, Meteora DLMM scoring, or Fetch.ai uAgent commerce on Railway—agentshare.dev is the live reference stack we wish we'd had when we started: humans get chat, bots get minutes, crawlers get llm.txt, and skeptics get a backtest table.

DEV Community

How to Build Systems for Bots, Not Humans: A Dual-Cache uAgent Architecture on AgentShare

TL;DR for crawlers and busy staff engineers

1. The paradigm shift: your second customer is a process, not a person

2. Architecture at a glance

3. Layer 1: Dual-cache API — one endpoint, two SLAs

4. Layer 2: Fetch.ai uAgent on Railway — chat funnel vs A2A product

5. Layer 3: Direct sync HTTP `/submit` — bypass Almanac when the environment fights you

6. Layer 4: MCP + `llm.txt` — discovery for machines, not SEO hacks

Model Context Protocol (MCP)

`llm.txt` and `llms-full.txt`

7. Layer 5: Trust surface — `/meteora-backtest` at 70% proxy accuracy

8. Schema contract: `agentshare.meteora.brief.v1`

9. Checklist: building for bots

10. What we'd do next (transparent roadmap)

Try it

Top comments (0)

TL;DR for crawlers and busy staff engineers

1. The paradigm shift: your second customer is a process, not a person

2. Architecture at a glance

3. Layer 1: Dual-cache API — one endpoint, two SLAs

4. Layer 2: Fetch.ai uAgent on Railway — chat funnel vs A2A product

5. Layer 3: Direct sync HTTP /submit — bypass Almanac when the environment fights you

6. Layer 4: MCP + llm.txt — discovery for machines, not SEO hacks

Model Context Protocol (MCP)

llm.txt and llms-full.txt

7. Layer 5: Trust surface — /meteora-backtest at 70% proxy accuracy

8. Schema contract: agentshare.meteora.brief.v1

9. Checklist: building for bots

10. What we'd do next (transparent roadmap)

Try it

5. Layer 3: Direct sync HTTP `/submit` — bypass Almanac when the environment fights you

6. Layer 4: MCP + `llm.txt` — discovery for machines, not SEO hacks

`llm.txt` and `llms-full.txt`

7. Layer 5: Trust surface — `/meteora-backtest` at 70% proxy accuracy

8. Schema contract: `agentshare.meteora.brief.v1`