Improve code examples

Author: vdusek

README.md

@@ -199,7 +199,7 @@ The full SDK documentation lives at **[docs.apify.com/sdk/python](https://docs.a
 | [Overview](https://docs.apify.com/sdk/python/docs/overview) | What the SDK is, what Actors are, and how the pieces fit together. |
 | [Quick start](https://docs.apify.com/sdk/python/docs/quick-start) | Create, run, and deploy your first Python Actor. |
 | [Concepts](https://docs.apify.com/sdk/python/docs/concepts/actor-lifecycle) | Actor lifecycle, input, storages, events, proxy management, interacting with other Actors, webhooks, accessing the Apify API, logging, configuration, and pay-per-event. |
-| [Guides](https://docs.apify.com/sdk/python/docs/guides/beautifulsoup-httpx) | Integrations with BeautifulSoup, Parsel, Playwright, Selenium, Crawlee, Scrapy, Scrapling, Crawl4AI, and Browser Use, plus hosting AI agents, building MCP servers, running a web server, validating input with Pydantic, and using uv. |
+| [Guides](https://docs.apify.com/sdk/python/docs/guides/beautifulsoup-httpx) | Integrations with BeautifulSoup, Parsel, Playwright, Selenium, Crawlee, Scrapy, Scrapling, Crawl4AI, and Browser Use, plus using uv, validating input with Pydantic, running a web server, building MCP servers, and hosting AI agents. |
 | [Upgrading](https://docs.apify.com/sdk/python/docs/upgrading/upgrading-to-v4) | Migrating between major versions. |
 | [API reference](https://docs.apify.com/sdk/python/reference) | Generated reference for every class and method. |
 | [Changelog](https://docs.apify.com/sdk/python/docs/changelog) | Release history and breaking changes. |

docs/03_guides/14_ai_agents.mdx

@@ -2,56 +2,98 @@
 import os
 
 from crewai import LLM, Agent, Crew, Task
-from crewai.tools import tool
+from crewai_tools import ApifyActorsTool
+from pydantic import BaseModel
 
 from apify import Actor
 
 OPENROUTER_BASE_URL = 'https://openrouter.apify.actor/api/v1'
 
 # On a fresh container, CrewAI shows a one-time trace-consent prompt that blocks on
-# stdin. `CREWAI_TESTING=true` is the only flag that suppresses it.
+# stdin. `CREWAI_TESTING=true` suppresses it.
 os.environ.setdefault('CREWAI_TESTING', 'true')
 
+# The Crawlee docs page the crew reads when the input has no `url`.
+DEFAULT_URL = 'https://crawlee.dev/python/docs/guides/architecture-overview'
 
-@tool('Average')
-def average(numbers: list[float]) -> float:
-    """Return the arithmetic mean of a list of numbers."""
-    return sum(numbers) / len(numbers)
+
+class ActorInput(BaseModel):
+    """The Actor input, validated with default values."""
+
+    url: str = DEFAULT_URL
+    model: str = 'openai/gpt-5.4-mini'
+
+
+class Crawler(BaseModel):
+    """One crawler class that Crawlee provides."""
+
+    name: str
+    built_on: str
+    best_for: str
+
+
+class CrawlerGuide(BaseModel):
+    """The structured guide the crew distills from the docs page."""
+
+    crawlers: list[Crawler]
 
 
 async def main() -> None:
     async with Actor:
-        actor_input = await Actor.get_input() or {}
-        query = actor_input.get('query', 'What is the average of 12, 18, and 30?')
-        model = actor_input.get('model', 'openai/gpt-4o-mini')
+        # Parse the Actor input into the typed model, filling in defaults.
+        actor_input = ActorInput.model_validate(await Actor.get_input() or {})
+        url = actor_input.url
+        model = actor_input.model
 
         # Route the LLM through the Apify OpenRouter proxy (no provider key needed).
-        # The `openai/` prefix selects CrewAI's OpenAI-compatible client. The rest
-        # is the OpenRouter model slug sent to the proxy.
+        # The `openai/` prefix selects CrewAI's OpenAI-compatible client.
         llm = LLM(
             model=f'openai/{model}',
             base_url=OPENROUTER_BASE_URL,
             api_key=os.environ['APIFY_TOKEN'],
         )
 
-        # A one-agent crew: an analyst that answers using the `average` tool.
-        analyst = Agent(
-            role='Data Analyst',
-            goal='Answer numeric questions accurately.',
-            backstory='An analyst who turns raw numbers into clear answers.',
-            tools=[average],
+        # `ApifyActorsTool` exposes any Apify Actor as a CrewAI tool. Here it wraps the
+        # RAG Web Browser to fetch the page as clean Markdown.
+        researcher = Agent(
+            role='Documentation researcher',
+            goal='Read the Crawlee docs and note every crawler it describes.',
+            backstory='A researcher who reads technical docs closely.',
+            tools=[ApifyActorsTool('apify/rag-web-browser')],
+            llm=llm,
+        )
+        writer = Agent(
+            role='Technical writer',
+            goal='Turn research notes into a clear, structured crawler guide.',
+            backstory='A writer who distills docs into comparison tables.',
             llm=llm,
         )
-        task = Task(
-            description=query,
-            expected_output='A short, readable answer to the query.',
-            agent=analyst,
+
+        research = Task(
+            description=f'Scrape {url} and list the crawlers the page covers.',
+            expected_output='Notes on each crawler: name, what it builds on, its use.',
+            agent=researcher,
+        )
+        # `context=[research]` feeds the researcher's notes to the writer, and
+        # `output_pydantic` makes the final task return a validated `CrawlerGuide`.
+        write = Task(
+            description=(
+                'From the notes, compile each crawler with what it is built on '
+                'and what it is best for.'
+            ),
+            expected_output='A list of crawlers with name, built_on, and best_for.',
+            agent=writer,
+            context=[research],
+            output_pydantic=CrawlerGuide,
         )
 
-        # `kickoff_async` keeps the Actor's event loop responsive.
-        result = await Crew(agents=[analyst], tasks=[task]).kickoff_async()
-        Actor.log.info(f'Crew result:\n{result.raw}')
-        await Actor.push_data({'query': query, 'answer': result.raw})
+        # `kickoff_async` runs the crew without blocking the Actor's event loop.
+        crew = Crew(agents=[researcher, writer], tasks=[research, write])
+        guide = (await crew.kickoff_async()).pydantic
+        if guide is None:
+            raise RuntimeError('The crew did not return a structured CrawlerGuide.')
+        Actor.log.info(f'Crawler guide:\n{guide.model_dump_json(indent=2)}')
+        await Actor.push_data([crawler.model_dump() for crawler in guide.crawlers])
 
 
 if __name__ == '__main__':

docs/03_guides/code/14_crewai.py

@@ -1,40 +1,104 @@
 import asyncio
 import os
+from functools import partial
+from typing import TypedDict
 
-from langchain.agents import create_agent
-from langchain_core.tools import tool
+from langchain_core.runnables import Runnable
 from langchain_openai import ChatOpenAI
+from langgraph.graph import END, START, StateGraph
+from pydantic import BaseModel
 
 from apify import Actor
 
 OPENROUTER_BASE_URL = 'https://openrouter.apify.actor/api/v1'
+MIN_KEY_POINTS = 3
+MAX_REVISIONS = 2
 
 
-@tool
-def sum_numbers(numbers: list[int]) -> int:
-    """Return the sum of a list of numbers."""
-    return sum(numbers)
+class ActorInput(BaseModel):
+    """The Actor input, validated with default values."""
+
+    url: str = 'https://crawlee.dev'
+    model: str = 'openai/gpt-5.4-mini'
+
+
+class PageSummary(BaseModel):
+    """The structured summary the agent extracts from a web page."""
+
+    title: str
+    summary: str
+    key_points: list[str]
+    target_audience: str
+
+
+class State(TypedDict):
+    """The state that flows between the graph's nodes."""
+
+    url: str
+    page_text: str
+    summary: PageSummary
+    revisions: int
+
+
+async def fetch(state: State) -> dict:
+    """Node: scrape the page to clean Markdown with the RAG Web Browser Actor."""
+    run_input = {'query': state['url'], 'outputFormats': ['markdown']}
+    run = await Actor.call('apify/rag-web-browser', run_input=run_input)
+    dataset = Actor.apify_client.dataset(run.default_dataset_id)
+    items = (await dataset.list_items()).items
+    if not items or not items[0].get('markdown'):
+        raise RuntimeError(f'RAG Web Browser returned no content for {state["url"]}.')
+    return {'page_text': items[0]['markdown']}
+
+
+async def summarize(state: State, structured_llm: Runnable) -> dict:
+    """Node: summarize the page, asking for more depth on a re-run."""
+    hint = ''
+    if state['revisions']:
+        hint = f' List at least {MIN_KEY_POINTS} distinct key points.'
+    prompt = f'Summarize this page.{hint}\n\n{state["page_text"]}'
+    summary = await structured_llm.ainvoke(prompt)
+    return {'summary': summary, 'revisions': state['revisions'] + 1}
+
+
+def route(state: State) -> str:
+    """Edge: loop back for another pass while the summary is thin."""
+    thin = len(state['summary'].key_points) < MIN_KEY_POINTS
+    if thin and state['revisions'] < MAX_REVISIONS:
+        return 'summarize'
+    return END
 
 
 async def main() -> None:
     async with Actor:
-        actor_input = await Actor.get_input() or {}
-        query = actor_input.get('query', 'What is the sum of 128, 64, and 32?')
-        model = actor_input.get('model', 'openai/gpt-4o-mini')
+        # Parse the Actor input into the typed model, filling in defaults.
+        actor_input = ActorInput.model_validate(await Actor.get_input() or {})
+        url = actor_input.url
+        model = actor_input.model
 
         # Route the LLM through the Apify OpenRouter proxy (no provider key needed).
         llm = ChatOpenAI(
             model=model,
             base_url=OPENROUTER_BASE_URL,
             api_key=os.environ['APIFY_TOKEN'],
         )
-        # The agent decides on its own when to call the `sum_numbers` tool.
-        agent = create_agent(llm, tools=[sum_numbers])
+        # `with_structured_output` makes the node return a validated `PageSummary`.
+        structured_llm = llm.with_structured_output(PageSummary)
+
+        # Wire the nodes into a graph. Its conditional edge loops back into `summarize`
+        # until the summary is detailed enough. `partial` binds `structured_llm` to it.
+        graph = StateGraph(State)
+        graph.add_node('fetch', fetch)
+        graph.add_node('summarize', partial(summarize, structured_llm=structured_llm))
+        graph.add_edge(START, 'fetch')
+        graph.add_edge('fetch', 'summarize')
+        graph.add_conditional_edges('summarize', route)
+        agent = graph.compile()
 
-        result = await agent.ainvoke({'messages': [('user', query)]})
-        answer = result['messages'][-1].content
-        Actor.log.info(f'Agent answer:\n{answer}')
-        await Actor.push_data({'query': query, 'answer': answer})
+        result = await agent.ainvoke({'url': url, 'revisions': 0})
+        summary = result['summary']
+        Actor.log.info(f'Page summary:\n{summary.model_dump_json(indent=2)}')
+        await Actor.push_data({'url': url, **summary.model_dump()})
 
 
 if __name__ == '__main__':

docs/03_guides/code/14_langgraph.py

@@ -1,39 +1,88 @@
 import asyncio
 import os
 
-from llama_index.core.agent import ReActAgent
-from llama_index.core.tools import FunctionTool
+from llama_index.core import Document, VectorStoreIndex
+from llama_index.embeddings.huggingface import HuggingFaceEmbedding
 from llama_index.llms.openai_like import OpenAILike
+from llama_index.readers.apify import ApifyActor
+from pydantic import BaseModel
 
 from apify import Actor
 
 OPENROUTER_BASE_URL = 'https://openrouter.apify.actor/api/v1'
+EMBED_MODEL = 'BAAI/bge-small-en-v1.5'
 
 
-def word_count(text: str) -> int:
-    """Return the number of words in the given text."""
-    return len(text.split())
+class ActorInput(BaseModel):
+    """The Actor input, validated with default values."""
+
+    urls: list[str] = [
+        'https://docs.apify.com/platform/actors',
+        'https://docs.apify.com/platform/storage/dataset',
+        'https://docs.apify.com/platform/proxy',
+    ]
+    question: str = 'How does Apify proxy work?'
+    model: str = 'openai/gpt-5.4-mini'
+
+
+class Answer(BaseModel):
+    """The grounded answer the query engine returns."""
+
+    answer: str
+    key_facts: list[str]
+
+
+def to_document(item: dict) -> Document:
+    """Map a Website Content Crawler item to a `Document` tagged with its URL."""
+    return Document(text=item['text'], metadata={'url': item['url']})
 
 
 async def main() -> None:
     async with Actor:
-        actor_input = await Actor.get_input() or {}
-        query = actor_input.get('query', 'How many words are in "Apify runs Actors"?')
-        model = actor_input.get('model', 'openai/gpt-4o-mini')
+        # Parse the Actor input into the typed model, filling in defaults.
+        actor_input = ActorInput.model_validate(await Actor.get_input() or {})
+        urls = actor_input.urls
+        question = actor_input.question
+        model = actor_input.model
 
         # Route the LLM through the Apify OpenRouter proxy (no provider key needed).
-        # `OpenAILike` is the LlamaIndex class for OpenAI-compatible endpoints.
         llm = OpenAILike(
             model=model,
             api_base=OPENROUTER_BASE_URL,
             api_key=os.environ['APIFY_TOKEN'],
             is_chat_model=True,
         )
-        agent = ReActAgent(tools=[FunctionTool.from_defaults(fn=word_count)], llm=llm)
+        # Embeddings run locally, so the proxy needs no embeddings endpoint.
+        embed_model = HuggingFaceEmbedding(model_name=EMBED_MODEL)
+
+        # Scrape the pages with the Website Content Crawler Actor and wrap each one
+        # in a `Document`. LlamaIndex then chunks and embeds them, so the query engine
+        # retrieves only the relevant passages.
+        reader = ApifyActor(apify_api_token=os.environ['APIFY_TOKEN'])
+        run_input = {'startUrls': [{'url': url} for url in urls], 'maxCrawlDepth': 0}
+        documents = await asyncio.to_thread(
+            reader.load_data,
+            actor_id='apify/website-content-crawler',
+            run_input=run_input,
+            dataset_mapping_function=to_document,
+        )
+        index = VectorStoreIndex.from_documents(documents, embed_model=embed_model)
+
+        # `output_cls` returns a validated `Answer`. The response still carries the
+        # retrieved `source_nodes`, so the answer can cite the pages it came from.
+        query_engine = index.as_query_engine(
+            llm=llm,
+            output_cls=Answer,
+            response_mode='compact',
+            similarity_top_k=4,
+        )
+        response = await query_engine.aquery(question)
 
-        response = await agent.run(user_msg=query)
-        Actor.log.info(f'Agent answer:\n{response}')
-        await Actor.push_data({'query': query, 'answer': str(response)})
+        answer = response.response
+        sources = [node.node.metadata['url'] for node in response.source_nodes]
+        record = {'question': question, **answer.model_dump(), 'sources': sources}
+        Actor.log.info(f'Answer:\n{answer.model_dump_json(indent=2)}')
+        await Actor.push_data(record)
 
 
 if __name__ == '__main__':