feat: add news-card-agent (ASI:One interactive cards example)

[gautammanak1]

Summary

Adds a new official example, news-card-agent/, that demonstrates agent-driven interactive cards on ASI:One without any payment protocol.

• Live news is rendered as a card_kind: "custom" element-tree (section → list of items with image, heading, text, source badge, and a primary Read Full Article button).
• Tapping a button triggers a follow-up ChatMessage whose TextContent is the button's selection payload. The agent parses it (handling both raw JSON for direct @mention and natural-language prose from the planner), looks up the cached article in ctx.storage, and renders a brand-new article detail card plus a clickable markdown link to the source. A Back to News button on the detail card re-renders the list for the last query.
• Multi-backend news cascade picks the highest-priority configured source: Tavily (topic: "news" web search, default) → NewsAPI.org (/top-headlines or /everything with NEWS_API_COUNTRY=any support) → Hacker News Firebase API (no key required, used as zero-config fallback).
• ASI1 One LLM (asi1-mini via https://api.asi1.ai/v1/chat/completions) polishes each article subtitle into a single tight sentence and writes the intro line above the card. All three LLM helpers degrade gracefully when no API key is set.
• Project structure mirrors fet-example/: agent.py, chat_proto.py, cards.py (element-tree builders), news_client.py, asi1_client.py, shared.py, requirements.txt, .env.example, and a comprehensive README.md.

Type of Change

• New agent example
• Bug fix
• Documentation update
• Refactor / cleanup
• Other

Checklist

• I have starred this repository.
• New community agents are under contributors/<agent-name>/ (not repo root). (N/A — this is a maintainer/official example added at the repo root alongside fet-example/ and gemini-quickstart/, as permitted by CONTRIBUTING.md.)
• I ran ruff check . (passes — All checks passed! on news-card-agent/).
• I ran ruff format . (applied — 6 files already formatted on news-card-agent/).
• I added/updated README.md for changed example(s) (new news-card-agent/README.md styled like a2a-uAgents-Integration/.../langgraph/readme.md, and registered in the root README.md LLM Integration index table).
• I added .env.example if environment variables are required (documents ASI_ONE_API_KEY, ASI_ONE_MODEL, TAVILY_API_KEY, NEWS_API_KEY, NEWS_API_COUNTRY).
• I added demo image/GIF (if applicable). (Not added in this PR — happy to follow up with an ASI:One screenshot of the news + detail card if requested.)
• I added agent profile link (if applicable). (Agent is local-mailbox only at this point; no Agentverse profile URL yet.)
• I updated contributors/CHANGELOG.md for community agent changes, or root CHANGELOG.md for other non-doc changes (root CHANGELOG.md updated — this is a maintainer example, so the root changelog is the correct file).
• I added my agent to the Community Contributors table in root README.md (if new agent). (N/A — official root example. Added to the LLM Integration index table instead.)
• I verified paths/commands used in docs (install, run, env block, ASI:One queries, simulated button-click JSON all match the source).
• I understand this PR requires maintainer review before merge (review-required CI).

Related Issue

None.

Notes for Reviewers

• No payment protocol: only the standard chat protocol is included via agent.include(chat_proto, publish_manifest=True). There is no payment.py and no FET/Stripe code paths.
• Card wire format: each ChatMessage carries a TextContent preamble + one MetadataContent block with card_protocol_version: "1", requires_card_interaction: "true", card_kind: "custom", and card_payload JSON-stringified — matches the agent-driven interactive cards spec.
• Payload limits: element-tree depth = 5 (list card) and 3 (detail card); payload size ≈ 1.3 KB / 0.9 KB. Well under the 8-level / 64 KB spec limits.
• Selection round-trip: shared.parse_card_selection() handles both inbound formats (raw JSON for direct @mention, regex over prose for the planner path) and is unit-checked for article_id, back_to_news, and "not a selection" cases.
• Zero-config run: omitting all news keys works — the agent falls back to the public Hacker News Firebase API and uses picsum-seeded placeholder images. Adding TAVILY_API_KEY (or NEWS_API_KEY) upgrades it automatically.
• Country handling: NEWS_API_COUNTRY=any (or blank, all, global, world) skips the country filter and routes the request through NewsAPI /everything so the call never fails the "country/category/sources required" validation.
• Live verified: a real Tavily call was made during development with query="latest tech news" — returned 3 articles with real image URLs and source domains (cnbc.com, cnet.com), confirming the request shape and response parsing.
• Suggested testing flow: python agent.py → on ASI:One send latest tech news → tap any Read Full Article → tap Back to News. The detail card also includes a markdown link [Open original article](<url>) in the chat bubble.

Made with Cursor