feat: add Task API and Monitor API tools by Mustafa-Esoofally · Pull Request #8071 · agno-agi/agno

Mustafa-Esoofally · 2026-05-22T23:25:44Z

Summary

Extends ParallelTools with Task API (deep research) and Monitor API (continuous web tracking):

Task API — deep research with structured output, citations, and confidence scores

run_task: synchronous research (blocks until complete)
create_task: async task creation for long-running research
get_task_result: retrieve completed task results
get_task_status: check task progress

Monitor API — continuous web tracking with scheduled runs

create_monitor: create event-stream monitor for query changes
list_monitors: list all monitors with filters
get_monitor_events: retrieve detected changes
cancel_monitor: permanently stop a monitor

Toolkit-level config (user sets, LLM doesn't decide):

default_processor: Task API quality tier
default_monitor_processor: Monitor API processor (lite/base)
default_monitor_frequency: How often monitors run (1h/1d/1w/30d)
default_timeout: Task result timeout
default_output_schema: Structured output schema

Type of change

New feature (non-breaking change which adds functionality)

Checklist

Formatted and validated: ./scripts/format.sh and ./scripts/validate.sh pass
Follows toolkit patterns: enable_* flags, json.dumps() returns, proper error handling
Search/Extract tools unchanged from main
Cookbooks added: 4 cookbooks demonstrating different use cases
Tested locally with real API key

Add 12 new methods to ParallelTools for deep research and continuous web tracking: Task API (deep research with citations): - run_task: synchronous deep research - create_task: async task creation - get_task_result: retrieve completed results - get_task_status: check task progress Monitor API (continuous web tracking): - create_monitor: event-stream based tracking - create_snapshot_monitor: task-output change detection - list_monitors: list all monitors - get_monitor: get monitor details - update_monitor: modify frequency/status - cancel_monitor: stop a monitor - trigger_monitor: force immediate run - get_monitor_events: retrieve detected events Requires parallel-web SDK v0.6.0+.

Add 4 cookbooks based on actual use cases from industry research: - parallel_competitive_intel.py: AI code editor market comparison - parallel_due_diligence.py: startup investment research with citations - parallel_sales_leads.py: funding announcement monitoring and lead enrichment - parallel_research_thesis.py: thesis validation with supporting/contradicting monitors Also switch from logger.* to log_* utilities per codebase convention.

Add POST /webhooks/{agent_id} endpoint that receives webhooks from external services (Parallel Monitor, GitHub, Stripe, etc.) and invokes the specified agent with the payload as context. - New router: libs/agno/agno/os/routers/webhooks/ - Opt-in via enable_webhooks=True on AgentOS - Agent runs in background, returns run_id immediately - Cookbook: parallel_webhook_monitor.py shows full pattern Flow: Parallel detects event → POSTs to webhook → AgentOS invokes agent → agent calls get_monitor_events() for details → processes events

- Remove webhook support from ParallelTools (use polling with get_monitor_events instead) - Fix SDK 0.6.0 compatibility: .monitors instead of .data, .next_cursor instead of .has_more - Fix processor options: "base" default instead of invalid "standard" - Fix frequency options: "1h", "1d", "1w", "30d" per Parallel docs - Update class docstring to match codebase patterns - Consolidate cookbooks from 9 to 3 high-value examples - Remove webhook router from AgentOS (revert app.py changes) - Delete unused webhook schema and router files

- Update all tool docstrings to match Gmail pattern - Rename cookbooks for clarity: - parallel_tools.py -> parallel_search.py - parallel_task_api.py -> parallel_task.py - parallel_monitor_api.py -> parallel_monitor.py

- parallel_news_search.py — search latest AI news - parallel_company_research.py — deep research with citations - parallel_funding_tracker.py — monitor funding announcements

…rams LLM cannot decide cost/quality tradeoffs - these are user decisions. Tools now only expose what LLM can infer from context: - run_task(input) / create_task(input) - create_monitor(query) - get_task_result(run_id) / get_task_status(run_id) Toolkit params: - default_processor: Task API processor tier - default_monitor_processor: Monitor API processor (lite/base) - default_monitor_frequency: How often monitors run - default_timeout: Task result timeout - default_output_schema: JSON schema for structured output

- Use 'Example N:' style comments - Remove 'API' language - Remove 'Uncomment to test' blocks - Show toolkit config variations as separate agents - Follow exa_tools.py / tavily_tools.py structure

SDK expects {"type": "json", "json_schema": {...}} not raw JSON schema

…Monitor - Search and Extract tools unchanged from main branch - Added Task API: run_task, create_task, get_task_result, get_task_status - Added Monitor API: create_monitor, list_monitors, get_monitor_events, cancel_monitor - New toolkit params for Task/Monitor config

- Task API: run_task, create_task, get_task_result, get_task_status - Monitor API: create_monitor, list_monitors, cancel_monitor, get_monitor_events - Error handling tests included

kausmeows · 2026-06-01T19:00:43Z

+
+            events = []
+            for event in response.events:
+                event_data: Dict[str, Any] = {


wrong, some does not exist on the parallel sdk

event_data["event_type"] = getattr(event, "type", None) # wrong: field is `event_type` event_data["created_at"] = str(getattr(event, "created_at", "")) # wrong: field is `event_date` if hasattr(event, "content"): # wrong: content lives under `event.output` if hasattr(event, "citations"): # wrong: citations live under `event.output.basis`

Should be fixed

kausmeows · 2026-06-01T19:07:14Z

    - Search API: AI-optimized web search that returns relevant excerpts tailored for LLMs
    - Extract API: Extract content from specific URLs in clean markdown format, handling JavaScript-heavy pages and PDFs
+    - Task API: Deep research with structured output and citations (enable_task=True)
+    - Monitor API: Track topics over time and get notified of changes (enable_monitor=True)


The Parallel SDK exposes monitor.update (change frequency/webhook/metadata) and monitor.retrieve (get one monitor by ID)

kausmeows · 2026-06-01T19:28:44Z

+    tools=[
+        ParallelTools(
+            enable_task=True,
+            default_output_schema={


as per their docs output schema can be given in different ways-
we need cookbook showing all.
docs- https://docs.parallel.ai/task-api/task-quickstart#output-schema-types

added a cookbook

kausmeows · 2026-06-01T19:32:08Z

+    # Task API — Deep research with structured output and citations
+    # -------------------------------------------------------------------------
+
+    def run_task(self, input: str) -> str:


i think we need another look at this- https://docs.parallel.ai/task-api/task-quickstart#polling-vs-webhooks-vs-sse

looks light its async but we have implemented it in a blocking way. read the docs more, we probably need to use that polling or something.

fixed. let's kep seprate tools so agent can control the task and also run parallel ones

kausmeows · 2026-06-01T19:34:31Z

+            enable_task=True,
+            default_output_schema={
+                "type": "json",
+                "json_schema": {


also something to check-
if the output schema is this then that means the agent's input should be a structured input right? can you check if this structured input is rightly getting injected to the agent?

Skipped structured input for now. Not sure how it would at toolkit level

kausmeows · 2026-06-01T19:37:56Z

this does not show what the main purpose is here-
can we add better cookbooks to showcase this. can refer to parallel docs for reference on how they have shown.

added more good cookbooks

- Fix get_monitor_events to use correct SDK field names: - event.event_type (not event.type) - event.event_date (not event.created_at) - event.output.content (not event.content) - event.output.basis (not event.citations) - Fix parallel_search to use excerpts (plural) not excerpt (singular) - Extract _format_task_output helper to avoid code duplication - Add get_monitor tool (monitor.retrieve) - Add update_monitor tool (monitor.update) - Update cookbook to show all 3 output schema types (auto, json, string) - Update tests to match corrected SDK field names

- parallel_task_options.py: All output schema types (auto, json, string), processor tiers (lite, base, pro), timeout configuration - parallel_monitor_options.py: Frequency options (1h to 30d), processor tiers (lite, base), output schemas, combined configurations

…schema types Shows the three output schema formats: 1. Auto schema: {"type": "auto"} 2. JSON schema: {"type": "json", "json_schema": {...}} 3. String schema: plain string description Removes separate option cookbooks in favor of one focused example.

Task API: - Remove run_task() blocking method - Keep create_task(), get_task_status(), get_task_result() for agent control - Rename input param to query to avoid shadowing builtin Cookbooks: - Move to cookbook/91_tools/parallel/ folder - Add 6 focused use-case cookbooks: - output_schemas.py: All 4 output schema types - company_enrichment.py: CRM data enrichment - market_research.py: Industry analysis reports - investment_monitor.py: Track funding & M&A - competitor_tracker.py: Competitive intelligence - news_search.py: Fast web search - Add README with API overview and quick start Fixes: - Auto schema requires 'pro' processor (not 'base') Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The previous 300s default silently failed for pro/ultra tier tasks, which Parallel documents as taking 3-25 minutes. Also pass the same value as the httpx-level timeout so the client does not give up before the server's api_timeout deadline (httpx default is 600s). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

kausmeows · 2026-06-02T05:45:01Z

+# =============================================================================
+# RUN
+# =============================================================================
+if __name__ == "__main__":


https://docs.parallel.ai/monitor-api/monitor-quickstart#monitor-api-quickstart

we have not implemented the monitor api correctly, this definitely needs a webhook otherwise there is no point. We should have that capability that you can pass a webhook url too and that webhook will recieve the events from parallel, thats the main usecase otherwise rn its not really doing anything.

i pushed an update in cookbook cookbook/91_tools/parallel/competitor_tracker.py to show how we get the events via agent in polling like fashion.

The original cookbook only demonstrated create_monitor, leaving the consumer side as a "now what?". Without webhooks, polling is the only consumption path, so the example now has two phases: create monitors on first run, then re-run with `check` to list monitors and pull events. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

## Summary Updates ParallelTools documentation to cover the Task API and Monitor API tools added in agno-agi/agno#8071. **Changes:** - Expanded `tools/toolkits/search/parallel.mdx` from ~80 lines to ~225 lines - Added Task API section with processor tiers (lite/base/pro/ultra) and output schema types - Added Monitor API section with frequency options and two-phase usage pattern - Updated MCP endpoint from deprecated `search-mcp.parallel.ai` to `search.parallel.ai` - Made API key optional (keyless access is rate-limited) - Updated all example pages with current code patterns ## Files Changed | File | Description | |------|-------------| | `tools/toolkits/search/parallel.mdx` | Main toolkit documentation | | `tools/mcp/usage/parallel.mdx` | MCP server usage | | `examples/tools/parallel-tools.mdx` | Toolkit examples | | `examples/tools/mcp/parallel.mdx` | MCP example | ## Related - agno-agi/agno#8071 (feat: add Task API and Monitor API tools) - agno-agi/agno#8202 (cookbook: update Parallel MCP to use free endpoint)

Mustafa-Esoofally requested a review from a team as a code owner May 22, 2026 23:25

Mustafa-Esoofally added 18 commits May 22, 2026 19:30

cookbook: add scheduled monitor pattern with AgentOS scheduler

77b0e88

Merge branch 'main' into feat/exa-task-monitor-api

1ac84c2

fix(parallel): use log_error instead of log_exception

5992451

fix(parallel): correct search mode options to match SDK

db0c272

refactor(parallel): reduce monitor tools to essential 4

06d4e4f

fix(parallel): restore toolkit name and include exception in log_error

fc893eb

refactor(parallel): standardize docstrings and rename cookbooks

de02c49

- Update all tool docstrings to match Gmail pattern - Rename cookbooks for clarity: - parallel_tools.py -> parallel_search.py - parallel_task_api.py -> parallel_task.py - parallel_monitor_api.py -> parallel_monitor.py

refactor(cookbook): rename parallel cookbooks to use-case names

8acb085

- parallel_news_search.py — search latest AI news - parallel_company_research.py — deep research with citations - parallel_funding_tracker.py — monitor funding announcements

cookbook: add parallel_tools.py basic overview

99ac474

fix(cookbook): restore parallel_tools.py to main pattern

1972b5a

refactor(cookbook): update parallel cookbooks to match codebase pattern

50bc676

- Use 'Example N:' style comments - Remove 'API' language - Remove 'Uncomment to test' blocks - Show toolkit config variations as separate agents - Follow exa_tools.py / tavily_tools.py structure

fix(parallel): correct output_schema format per SDK

b732430

SDK expects {"type": "json", "json_schema": {...}} not raw JSON schema

Merge branch 'main' into feat/exa-task-monitor-api

d47722d

Mustafa-Esoofally changed the title ~~feat(parallel): add Task API and Monitor API tools~~ feat: add Task API and Monitor API tools Jun 1, 2026

Mustafa-Esoofally added 2 commits June 1, 2026 11:47

test(parallel): add unit tests for Task and Monitor API tools

736fec3

- Task API: run_task, create_task, get_task_result, get_task_status - Monitor API: create_monitor, list_monitors, cancel_monitor, get_monitor_events - Error handling tests included

Merge branch 'main' into feat/exa-task-monitor-api

4f33685

kausmeows reviewed Jun 1, 2026

View reviewed changes

Merge branch 'main' into feat/exa-task-monitor-api

704ecf3

kausmeows reviewed Jun 1, 2026

View reviewed changes

Mustafa-Esoofally and others added 4 commits June 1, 2026 16:00

Merge branch 'main' into feat/exa-task-monitor-api

b24683a

kausmeows reviewed Jun 2, 2026

View reviewed changes

Comment thread libs/agno/agno/tools/parallel.py Outdated

kausmeows and others added 2 commits June 2, 2026 11:07

chore: fix default output schema type init

990e075

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

kausmeows reviewed Jun 2, 2026

View reviewed changes

kausmeows and others added 2 commits June 2, 2026 11:21

update

254d151

kausmeows approved these changes Jun 2, 2026

View reviewed changes

Merge branch 'main' into feat/exa-task-monitor-api

b25403a

Mustafa-Esoofally merged commit d2008ed into main Jun 2, 2026
5 checks passed

Mustafa-Esoofally deleted the feat/exa-task-monitor-api branch June 2, 2026 14:54

Mustafa-Esoofally mentioned this pull request Jun 2, 2026

docs: add Task API and Monitor API to ParallelTools agno-agi/docs#672

Merged

Conversation

Mustafa-Esoofally commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Type of change

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kausmeows Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kausmeows Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kausmeows Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Mustafa-Esoofally commented May 22, 2026 •

edited

Loading

kausmeows Jun 1, 2026 •

edited

Loading

kausmeows Jun 1, 2026 •

edited

Loading

kausmeows Jun 2, 2026 •

edited

Loading