feat: add Agent-readable install guide (one URL to rule them all)
Users just paste one line to their AI Agent: 'Install Agent Eyes: https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md' The Agent reads the guide, installs, configures, and reports back. Inspired by oh-my-opencode's installation flow. Also updated README: new tagline, architecture diagram reflects pure-glue design, updated credits.
This commit is contained in:
Panniantong
@@ -2,31 +2,30 @@
|
|||||||
|
|
||||||
**Give your AI Agent eyes to see the entire internet.**
|
**Give your AI Agent eyes to see the entire internet.**
|
||||||
|
|
||||||
Agent Eyes is infrastructure for the Agent world — install once, and your AI Agent can search and read content across 10+ platforms. Zero to minimal configuration.
|
Agent Eyes is an open-source Agent capability aggregator. It combines the best free tools into one install, so any AI Agent can search and read the entire internet.
|
||||||
|
|
||||||
> *Built on top of [x-reader](https://github.com/runesleo/x-reader) by [@runes_leo](https://x.com/runes_leo) — thank you for the amazing open-source work. 🙏*
|
> Not a framework. Not a library. Just glue — beautifully simple glue that gives your Agent superpowers.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Why Agent Eyes?
|
## Install (One Line)
|
||||||
|
|
||||||
AI Agents are powerful, but blind. They can't browse Reddit, search Twitter, or read WeChat articles. Agent Eyes fixes that.
|
**Copy this to your AI Agent** (Claude Code, OpenClaw, Cursor, ChatGPT, etc.):
|
||||||
|
|
||||||
- **One install, 10+ platforms** — web pages, GitHub, Reddit, Twitter, YouTube, Bilibili, WeChat, XiaoHongShu, RSS, Telegram
|
```
|
||||||
- **Search + Read** — not just URL extraction, but actual search capability (find, then read)
|
Install and configure Agent Eyes by following the instructions here:
|
||||||
- **Agent-native design** — CLI, MCP Server, Python API — works with any AI Agent platform
|
https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md
|
||||||
- **Mostly free** — 99% of features cost nothing. One free API key unlocks full search.
|
```
|
||||||
|
|
||||||
---
|
Your Agent reads the guide, installs everything, and configures itself. You just watch.
|
||||||
|
|
||||||
## Quick Start
|
**Or install manually:**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Install
|
|
||||||
pip install git+https://github.com/Panniantong/agent-eyes.git
|
pip install git+https://github.com/Panniantong/agent-eyes.git
|
||||||
|
agent-eyes doctor # See what's available
|
||||||
# Check what's available
|
agent-eyes setup # Unlock more (optional)
|
||||||
agent-eyes doctor
|
```
|
||||||
|
|
||||||
# Read any URL (works immediately, no config needed)
|
# Read any URL (works immediately, no config needed)
|
||||||
agent-eyes read "https://github.com/openai/gpt-4"
|
agent-eyes read "https://github.com/openai/gpt-4"
|
||||||
@@ -213,43 +212,48 @@ Run `agent-eyes setup` to unlock more!
|
|||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
Agent Eyes is **not** a fork of x-reader. It's a layer built on top of it.
|
Agent Eyes is pure glue. Every channel is a thin wrapper (~50 lines) around an external tool. **Swap any backend by changing one file.**
|
||||||
|
|
||||||
```
|
```
|
||||||
┌──────────────────────────────────────┐
|
┌─────────────────────────────────────────┐
|
||||||
│ Agent Eyes │
|
│ Agent Eyes (pure glue) │
|
||||||
│ ┌──────────┐ ┌──────────────────┐ │
|
│ │
|
||||||
│ │ Search │ │ Config + Doctor │ │
|
│ ┌─────────────────────────────────────┐│
|
||||||
│ │ Exa │ │ Setup Wizard │ │
|
│ │ Pluggable Channels ││
|
||||||
│ │ Reddit │ │ Health Check │ │
|
│ │ ││
|
||||||
│ │ GitHub │ │ │ │
|
│ │ web.py → Jina Reader API ││
|
||||||
│ │ Twitter │ │ Agent Guides │ │
|
│ │ github.py → GitHub API ││
|
||||||
│ └──────────┘ └──────────────────┘ │
|
│ │ twitter.py → birdx + Jina ││
|
||||||
│ ┌──────────────────────────────────┐│
|
│ │ youtube.py → yt-dlp ││
|
||||||
│ │ Readers (based on x-reader) ││
|
│ │ reddit.py → Reddit JSON API ││
|
||||||
│ │ Web · GitHub · Reddit · Twitter ││
|
│ │ bilibili.py → Bilibili API ││
|
||||||
│ │ YouTube · Bilibili · WeChat ││
|
│ │ rss.py → feedparser ││
|
||||||
│ │ XHS · RSS · Telegram ││
|
│ │ exa.py → Exa Search API ││
|
||||||
│ └──────────────────────────────────┘│
|
│ │ ││
|
||||||
│ ┌──────────────────────────────────┐│
|
│ │ ↑ Swap any backend, nothing else ││
|
||||||
│ │ Integrations ││
|
│ │ changes. Just edit one file. ││
|
||||||
│ │ CLI · MCP Server · OpenClaw Skill│
|
│ └─────────────────────────────────────┘│
|
||||||
│ └──────────────────────────────────┘│
|
│ ┌──────────┐ ┌──────────────────────┐ │
|
||||||
└──────────────────────────────────────┘
|
│ │ Config │ │ Integrations │ │
|
||||||
|
│ │ Doctor │ │ CLI · MCP · Skill │ │
|
||||||
|
│ │ Guides │ │ Python API │ │
|
||||||
|
│ └──────────┘ └──────────────────────┘ │
|
||||||
|
└─────────────────────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
- **Readers**: Content extraction from URLs (internalized from x-reader, MIT license)
|
**Design principle**: Agent Eyes doesn't reinvent wheels. It aggregates the best free tools and makes them accessible to any AI Agent with one install.
|
||||||
- **Search**: Semantic search across platforms (Agent Eyes original)
|
|
||||||
- **Config + Doctor**: Configuration management and health checks (Agent Eyes original)
|
|
||||||
- **Integrations**: CLI, MCP Server, OpenClaw Skill (Agent Eyes original)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Credits
|
## Credits
|
||||||
|
|
||||||
- **[x-reader](https://github.com/runesleo/x-reader)** by [@runes_leo](https://x.com/runes_leo) — the URL-to-content extraction engine that Agent Eyes is built upon. MIT License.
|
Agent Eyes stands on the shoulders of these amazing open-source projects:
|
||||||
- **[Exa](https://exa.ai)** — semantic search API powering web/Reddit/Twitter search.
|
|
||||||
- **[birdx](https://github.com/runesleo/birdx)** — Twitter CLI tool for advanced Twitter features.
|
- **[Jina Reader](https://r.jina.ai)** — web page reading
|
||||||
|
- **[birdx](https://github.com/runesleo/birdx)** by [@runes_leo](https://x.com/runes_leo) — Twitter access
|
||||||
|
- **[Exa](https://exa.ai)** — semantic search
|
||||||
|
- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** — YouTube transcripts
|
||||||
|
- **[feedparser](https://github.com/kurtmckee/feedparser)** — RSS/Atom feeds
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
|
|||||||
+201
@@ -0,0 +1,201 @@
|
|||||||
|
# Agent Eyes — Installation Guide
|
||||||
|
|
||||||
|
## For Humans
|
||||||
|
|
||||||
|
Copy and paste this to your AI Agent (Claude Code, OpenClaw, Cursor, ChatGPT, etc.):
|
||||||
|
|
||||||
|
```
|
||||||
|
Install and configure Agent Eyes by following the instructions here:
|
||||||
|
https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md
|
||||||
|
```
|
||||||
|
|
||||||
|
That's it. Your Agent will handle the rest.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## For AI Agents
|
||||||
|
|
||||||
|
Welcome! You're about to give your user's Agent (that's you!) eyes to see the entire internet.
|
||||||
|
Agent Eyes lets you search and read content across 10+ platforms with one install.
|
||||||
|
|
||||||
|
### Step 1: Install Agent Eyes
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install git+https://github.com/Panniantong/agent-eyes.git
|
||||||
|
```
|
||||||
|
|
||||||
|
If `pip` fails, try:
|
||||||
|
```bash
|
||||||
|
pip3 install git+https://github.com/Panniantong/agent-eyes.git
|
||||||
|
```
|
||||||
|
|
||||||
|
If permission error, try:
|
||||||
|
```bash
|
||||||
|
pip install --user git+https://github.com/Panniantong/agent-eyes.git
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2: Verify Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
agent-eyes version
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected output: `Agent Eyes v1.0.0` (or higher)
|
||||||
|
|
||||||
|
If this works, run a health check:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
agent-eyes doctor
|
||||||
|
```
|
||||||
|
|
||||||
|
This shows which platforms are already available (many work with zero configuration).
|
||||||
|
|
||||||
|
### Step 3: Test Zero-Config Features
|
||||||
|
|
||||||
|
These work immediately without any setup:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Read a web page
|
||||||
|
agent-eyes read "https://example.com"
|
||||||
|
|
||||||
|
# Read a GitHub repo
|
||||||
|
agent-eyes read "https://github.com/Panniantong/agent-eyes"
|
||||||
|
|
||||||
|
# Search GitHub
|
||||||
|
agent-eyes search-github "AI agent framework" -n 3
|
||||||
|
```
|
||||||
|
|
||||||
|
Tell the user: "✅ Agent Eyes installed! I can now read web pages, GitHub, YouTube, Bilibili, RSS, and tweets. Want me to unlock search too? (free, takes 30 seconds)"
|
||||||
|
|
||||||
|
### Step 4: Unlock Search (Optional, Recommended)
|
||||||
|
|
||||||
|
Ask the user:
|
||||||
|
|
||||||
|
> "I can unlock full web search, Reddit search, and Twitter search with one free API key. Want to set it up? It takes 30 seconds."
|
||||||
|
|
||||||
|
If the user says yes:
|
||||||
|
|
||||||
|
> "Please go to https://exa.ai, sign up (free), and copy your API key. Then send it to me."
|
||||||
|
|
||||||
|
When the user provides the key:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Write the key to config
|
||||||
|
python3 -c "
|
||||||
|
from agent_eyes.config import Config
|
||||||
|
c = Config()
|
||||||
|
c.set('exa_api_key', 'THE_KEY_USER_PROVIDED')
|
||||||
|
print('✅ Exa API key saved!')
|
||||||
|
"
|
||||||
|
```
|
||||||
|
|
||||||
|
Test it:
|
||||||
|
```bash
|
||||||
|
agent-eyes search "AI agent infrastructure" -n 3
|
||||||
|
```
|
||||||
|
|
||||||
|
Tell the user: "✅ Search unlocked! I can now search the entire web, Reddit, and Twitter for you."
|
||||||
|
|
||||||
|
### Step 5: Optional — Advanced Channels
|
||||||
|
|
||||||
|
Only offer these if the user asks or if relevant to their needs.
|
||||||
|
|
||||||
|
#### Twitter Advanced (search timelines, read threads)
|
||||||
|
|
||||||
|
Check if birdx is available:
|
||||||
|
```bash
|
||||||
|
which birdx && echo "already installed" || pip install birdx
|
||||||
|
```
|
||||||
|
|
||||||
|
If birdx is installed, it works automatically. If the user wants to configure cookie auth for deeper access, read the guide:
|
||||||
|
`agent_eyes/guides/setup-twitter.md`
|
||||||
|
|
||||||
|
#### Reddit Full Reader (read complete posts + comments)
|
||||||
|
|
||||||
|
Reddit blocks many server IPs. Full reading requires a proxy.
|
||||||
|
Read the guide: `agent_eyes/guides/setup-reddit.md`
|
||||||
|
|
||||||
|
Without a proxy, you can still SEARCH Reddit content via Exa (Step 4).
|
||||||
|
|
||||||
|
#### WeChat / XiaoHongShu (Chinese platforms)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install agent-eyes[browser]
|
||||||
|
playwright install chromium
|
||||||
|
```
|
||||||
|
|
||||||
|
For XiaoHongShu, the user needs to log in once. Read: `agent_eyes/guides/setup-xiaohongshu.md`
|
||||||
|
|
||||||
|
### Step 6: Final Health Check
|
||||||
|
|
||||||
|
```bash
|
||||||
|
agent-eyes doctor
|
||||||
|
```
|
||||||
|
|
||||||
|
Report the results to the user in a friendly way. Example:
|
||||||
|
|
||||||
|
> "Here's what I can do now:
|
||||||
|
> ✅ Read: Web, GitHub, YouTube, Bilibili, RSS, Tweets
|
||||||
|
> ✅ Search: Web, GitHub, Reddit, Twitter
|
||||||
|
> ⬜ Not configured: Reddit full reader, WeChat, XiaoHongShu
|
||||||
|
>
|
||||||
|
> I'm ready to help! Ask me to search or read anything."
|
||||||
|
|
||||||
|
### Using Agent Eyes
|
||||||
|
|
||||||
|
After installation, you can use these commands anytime:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Read any URL
|
||||||
|
agent-eyes read "<url>"
|
||||||
|
|
||||||
|
# Search the web
|
||||||
|
agent-eyes search "<query>"
|
||||||
|
|
||||||
|
# Search specific platforms
|
||||||
|
agent-eyes search-github "<query>"
|
||||||
|
agent-eyes search-reddit "<query>" --sub "<subreddit>"
|
||||||
|
agent-eyes search-twitter "<query>"
|
||||||
|
|
||||||
|
# Check status
|
||||||
|
agent-eyes doctor
|
||||||
|
```
|
||||||
|
|
||||||
|
Or use the Python API:
|
||||||
|
```python
|
||||||
|
from agent_eyes import AgentEyes
|
||||||
|
import asyncio
|
||||||
|
|
||||||
|
eyes = AgentEyes()
|
||||||
|
result = asyncio.run(eyes.read("https://any-url.com"))
|
||||||
|
results = asyncio.run(eyes.search("any query"))
|
||||||
|
```
|
||||||
|
|
||||||
|
### MCP Server (for Claude Code, Cursor, etc.)
|
||||||
|
|
||||||
|
If your platform supports MCP:
|
||||||
|
```bash
|
||||||
|
pip install agent-eyes[mcp]
|
||||||
|
```
|
||||||
|
|
||||||
|
Add to MCP config:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"agent-eyes": {
|
||||||
|
"command": "python3",
|
||||||
|
"args": ["-m", "agent_eyes.integrations.mcp_server"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Troubleshooting
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
|---------|----------|
|
||||||
|
| `pip: command not found` | Try `pip3` instead |
|
||||||
|
| `Permission denied` | Add `--user` flag or use `sudo` |
|
||||||
|
| `agent-eyes: command not found` | Run `python3 -m agent_eyes.cli doctor` instead |
|
||||||
|
| Search returns "Exa API key not configured" | Run Step 4 above |
|
||||||
|
| Reddit returns 403 | Need proxy (see `guides/setup-reddit.md`) |
|
||||||
Reference in New Issue
Block a user