![\"pi-exa](\"assets/screenshot.png\")
\n\n \n
Configure Exa tools from the settings overlay.
\n\n---\n\n\n ![\"web_search_exa](\"assets/web_search_exa.png\")
\n
Readable web search previews keep the UI clean while full tool output remains available to the agent.
\n\n[Exa](https://exa.ai)-powered web search, content retrieval, answers, and agentic search tools for [pi](https://pi.dev). This package has parity with the official Exa MCP server's current search and content-retrieval tools, then adds two Pi-specific capabilities: Exa's Answer API and the newly announced Exa Agent API for long-running research workflows.\n\nIt also ships a bundled `exa-search` skill that guides the agent on when to search, when to fetch, when to use Answer, and when to escalate to Exa Agent without flooding context.\n\n## Prerequisites\n\nYou need an [Exa API key](https://dashboard.exa.ai/api-keys).\n\n## Install\n\n```bash\npi install npm:@alasano/pi-exa\n```\n\n## Authentication\n\nSet `EXA_API_KEY` in the environment before starting pi, or run:\n\n```sh\n/exa-auth set\n```\n\nThe command stores credentials under the pi agent directory for this package only.\n\n## Settings\n\nRun `/exa-settings` to open the tool settings overlay. Search, advanced search, fetch, and answer can be toggled individually. Agent lifecycle tools are toggled as one group so create/get/list/cancel/delete/events stay consistent.\n\nDisabled tools are removed from the agent's active tool list immediately for the next turn.\n\n## Skill\n\nThe package includes the `exa-search` skill. It guides the agent to:\n\n- start with lightweight search for source discovery\n- use advanced search only when filters or content controls matter\n- fetch selected URLs instead of dumping broad page text\n- use Answer for concise sourced answers\n- use the newly announced Exa Agent API for deeper multi-hop or long-running async research workflows\n- retrieve the full stored Agent result after compact background completion notices\n\n## Workflow\n\nUse the tools as a pipeline:\n\n1. `web_search_exa` for normal source discovery.\n2. `web_search_advanced_exa` when domains, dates, categories, freshness, summaries, highlights, subpages, or extracted text matter.\n3. `web_fetch_exa` for selected URLs that need full markdown content.\n4. `web_answer_exa` when a direct answer with sources is enough.\n5. `web_agent_exa` when the task is bigger than search: long-running research, multi-hop source gathering, or structured output across many sources.\n\nForeground Agent runs return the full Agent result to the agent. Background Agent runs return promptly, show a persistent status panel, and send a compact completion notice that tells the agent to call `web_agent_get_exa` before using detailed findings.\n\n## Tools (10)\n\n### Search, Content, And Answers\n\n| Tool | Description |\n| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `web_search_exa` | Search the web with compact, highlight-first results for normal source discovery. |\n| `web_search_advanced_exa` | Search with filters and content controls: domains, dates, categories, freshness, summaries, highlights, subpages, text extraction, and response context. |\n| `web_fetch_exa` | Retrieve clean markdown/text content from selected known URLs. Defaults to bounded content so fetches stay focused. |\n| `web_answer_exa` | Ask Exa's Answer API for a direct sourced answer when a result list would be too much. |\n\n### Exa Agent\n\n`web_agent_exa` is the main Agent tool. Use it for high-value async workflows that need more than search/fetch/answer: long-running research, structured JSON output, or multi-hop source gathering.\n\n| Tool | Role |\n| ---------------------- | -------------------------------------------------------------------------------------------------------------- |\n| `web_agent_exa` | Create an Agent run. Supports foreground wait mode and background tracking. |\n| `web_agent_get_exa` | Retrieve the full stored Agent result, including text, structured output, citation grounding, usage, and cost. |\n| `web_agent_list_exa` | List recent Agent runs to find IDs or inspect statuses. |\n| `web_agent_cancel_exa` | Cancel a queued or running Agent run. |\n| `web_agent_delete_exa` | Delete a stored Agent run when explicitly requested. |\n| `web_agent_events_exa` | Inspect stored lifecycle events or replay the event stream for debugging/progress history. |\n\n## Agent Modes\n\n| Mode | Behavior |\n| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `mode: \"wait\", monitor: \"stream\"` | Foreground run with server-sent lifecycle events. Best default when the user needs the result in the current turn. |\n| `mode: \"wait\", monitor: \"poll\"` | Foreground run using `GET /agent/runs/{id}` polling. Useful if streaming is undesirable. |\n| `mode: \"background\"` | Returns the run ID immediately, tracks the run in a pi widget, and sends a compact follow-up when it finishes. `monitor` is ignored in background mode. |\n\n## Output And Context Discipline\n\n- Search defaults to compact highlights rather than full page text.\n- Advanced search returns extracted text by default; use `textMaxCharacters` for broad queries.\n- Fetch is for selected known URLs, not broad discovery.\n- Agent foreground/get results return full structured output and citation grounding to the agent.\n- Background completion notices stay compact and instruct the agent to retrieve the full result before answering in detail.\n- Ctrl+O in the UI exposes expanded previews/raw API diagnostics without changing what the agent receives.\n","readmeFilename":"README.md"}