Hosting AI agents

Copy for LLM

In this guide, you'll learn how to host an AI agent as an Apify Actor, using the agent framework of your choice.

Introduction

An AI agent is a program that uses a large language model (LLM) to decide what to do next. Instead of following a fixed script, it reasons about a task, calls tools to gather information or take actions, and loops until the task is done. The Python ecosystem offers several frameworks for building such agents, and the Apify SDK doesn't lock you into any of them.

Apify Actors are well suited to hosting agents:

• An agent is just a Python program, so wrap it in async with Actor: to run it on the Apify platform.
• The platform scales runs, schedules them, and keeps logs, so you don't operate any infrastructure yourself.
• Apify Store gives your agent thousands of ready-made tools. Any Actor can become a tool the agent calls: a scraper, a browser automation, an API wrapper.
• The Apify OpenRouter proxy lets the agent talk to an LLM without managing a provider API key.
• The pay-per-event charging lets you monetize the agent and pass LLM costs on to its users.

Each example in this guide shows a complete, single-file Actor for one framework. They all read the input, run the agent, and store the result in the default dataset. Each one defines its input as a Pydantic model with default values, so the fields stay typed and validated.

Choosing a framework

Apify maintains a ready-made Actor template for each of the popular agent frameworks. Each template is a complete, deployable Actor that you can use as a starting point.

Framework	Good for	Template
LangGraph	Graph-based agents with explicit state and control flow	python-langgraph
CrewAI	Multi-agent "crews" that collaborate on a task	python-crewai
PydanticAI	Typed, Pydantic-native agents with tool calling	python-pydanticai
LlamaIndex	Retrieval-augmented agents over your own data	python-llamaindex-agent
Smolagents	Lightweight code-writing agents	python-smolagents

All of these templates live in the actor-templates repository. To create a project, use the Apify CLI, for example:

apify create my-agent --template python-pydanticai

Connecting to an LLM

There are two ways to give an agent an LLM.

Apify OpenRouter proxy

The Apify OpenRouter proxy is an OpenAI-compatible endpoint at https://openrouter.apify.actor/api/v1 that fronts the full OpenRouter model catalog. Any framework with an OpenAI-compatible client can point its base URL at the proxy, which is what every example in this guide does. Note that:

• The token usage is billed against the Apify account running the Actor, so no provider API key is required.
• The Actor authenticates with the proxy using the APIFY_TOKEN that the platform injects into every run.
• To switch models, change the model input to any OpenRouter model slug, for example openai/gpt-5.4-mini.

Your own provider key

Call a provider such as OpenAI directly with your own API key. Keep the key out of the Actor input and source code. Read it from an environment variable, which on the platform you set as a secret environment variable and locally you export in your shell.

LangGraph

LangGraph models an agent as a graph, where nodes do the work and edges decide what runs next. The explicit state and control flow make complex, multi-step logic easy to follow, including loops that revisit earlier nodes. It builds on LangChain, so any LangChain chat model works. To install it, use:

pip install langchain-openai langchain-core langgraph pydantic

The install also includes Pydantic for the Actor's typed input and output models.

The following Actor builds a small graph with two nodes. A fetch node scrapes the page with the RAG Web Browser Actor, then a summarize node distills the clean Markdown into a structured summary. A conditional edge loops back into summarize until the summary is detailed enough:

Run on

import asyncio
import os
from functools import partial
from typing import TypedDict

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


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:
    """A node that scrapes 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:
    """A node that summarizes 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:
    """A conditional edge that loops 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:
        # 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'],
        )

        # `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({'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__':
    asyncio.run(main())

Note that:

• ChatOpenAI points its base_url at the Apify OpenRouter proxy, so any LangChain chat model works without a provider key. with_structured_output(PageSummary) makes the summarize node return a validated PageSummary.
• The State is a typed dict that flows between nodes. Each node returns a partial update, and LangGraph merges it into the shared state.
• StateGraph wires the nodes together: fetch runs first, then summarize. The route function is a conditional edge that either loops back into summarize for another pass or ends the run. The cycle and the revisions guard in the state are what a plain chain can't express, and they're the reason to reach for LangGraph.
• fetch scrapes the page by calling the RAG Web Browser Actor with Actor.call, then reads the result from its dataset. The Actor returns clean Markdown, so the agent reads text instead of raw HTML and uses fewer tokens. Any Apify scraping Actor works here. For details, see Using Apify Actors as tools.

CrewAI

CrewAI models a problem as a "crew" of role-playing agents, each with its own role, goal, and backstory. The agents work through tasks in sequence, handing results from one agent to the next. It fits well when a job splits into specialized roles that collaborate. To install it, use:

pip install crewai pydantic

The install also includes Pydantic for the Actor's typed input and output models.

The following Actor runs a two-agent crew. A researcher scrapes a Crawlee docs page with the RAG Web Browser Actor, exposed to the crew through a small custom tool. A writer then distills the notes into a structured guide of Crawlee's crawlers, each with its name, what it's built on, and what it's best for:

Run on

import asyncio
import os

from crewai import LLM, Agent, Crew, Task
from crewai.tools import BaseTool
from pydantic import BaseModel, Field

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` suppresses it.
os.environ.setdefault('CREWAI_TESTING', 'true')


class ActorInput(BaseModel):
    """The Actor input, validated with default values."""

    url: str = 'https://crawlee.dev/python/docs/guides/architecture-overview'
    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]


class WebBrowserToolInput(BaseModel):
    """The single argument the agent passes to the web browser tool."""

    url: str = Field(description='The URL of the web page to fetch.')


class WebBrowserTool(BaseTool):
    """A minimal CrewAI tool that runs an Apify Actor to fetch a page as Markdown."""

    name: str = 'web_browser'
    description: str = 'Fetch a web page and return its content as clean Markdown.'
    args_schema: type[BaseModel] = WebBrowserToolInput

    async def _run(self, url: str) -> str:
        run = await Actor.call(
            actor_id='apify/rag-web-browser',
            run_input={'query': url, 'maxResults': 1},
        )
        dataset = Actor.apify_client.dataset(run.default_dataset_id)
        items = (await dataset.list_items()).items
        return '\n\n'.join(item.get('markdown') or '' for item in items)


async def main() -> None:
    async with Actor:
        # 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 = LLM(
            model=model,
            base_url=OPENROUTER_BASE_URL,
            api_key=os.environ['APIFY_TOKEN'],
            provider='openai',
        )

        # `WebBrowserTool` is our own Actor-backed tool, wrapping the RAG Web Browser
        # to fetch the page as clean Markdown.
        researcher = Agent(
            role='Documentation researcher',
            goal=(
                'Fetch the page with the web_browser tool and note every crawler '
                'it describes.'
            ),
            backstory=(
                'A researcher who never answers from memory. Before writing '
                'anything, always read the actual page with the web_browser tool '
                'and report only what it says.'
            ),
            tools=[WebBrowserTool()],
            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,
        )

        research = Task(
            description=(
                f'Use the web_browser tool to fetch {url}. Based only on the returned '
                'Markdown, list the crawlers the page covers. Do not use prior knowledge.'
            ),
            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,
        )

        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__':
    asyncio.run(main())

Note that:

• CrewAI's LLM points its base_url at the Apify OpenRouter proxy. The openai/ model prefix selects its OpenAI-compatible client, so no provider key is needed.
• The researcher reads the page with WebBrowserTool, a custom tool that runs the RAG Web Browser Actor and returns the page as clean Markdown. The writer then turns its notes into the result. Listing both agents in one Crew runs them in order, and context=[research] hands the researcher's notes to the writer.
• WebBrowserTool subclasses CrewAI's BaseTool, so the crew needs no third-party tool wrapper. Its _run method is async, and CrewAI runs it natively, so the tool awaits Actor.call directly with no manual event-loop bridge.
• output_pydantic=CrawlerGuide makes the writer's task return a validated CrawlerGuide, read from the crew result's .pydantic and stored as one dataset row per crawler.
• On a fresh container, CrewAI shows a one-time trace-consent prompt. The template sets CREWAI_TESTING=true to suppress it. Do the same in your Dockerfile.

PydanticAI

PydanticAI is an agent framework from the team behind Pydantic. It's strongly typed and integrates with the Pydantic models the Apify SDK already uses. Tool arguments and agent outputs are validated against your models, so the data stays structured end to end. To install it, use:

pip install pydantic-ai pydantic impit

The install also includes Pydantic for the Actor's typed input and output models, plus Impit, the HTTP client the Actor uses to call external APIs.

The following Actor evaluates a Python package and recommends whether to use it. Because the LLM would otherwise guess from its training data, the agent calls the fetch_pypi_metadata tool, which uses Impit to fetch live metadata from the PyPI JSON API. It then returns a typed report with the package's name, its latest version, a short summary, and a recommendation grounded in those facts:

Run on

import asyncio
import os
from http import HTTPStatus

import impit
from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

from apify import Actor

OPENROUTER_BASE_URL = 'https://openrouter.apify.actor/api/v1'
PYPI_JSON_URL = 'https://pypi.org/pypi/{name}/json'


class ActorInput(BaseModel):
    """The Actor input, validated with default values."""

    package: str = 'crawlee'
    model: str = 'openai/gpt-5.4-mini'


class PackageFacts(BaseModel):
    """The metadata the tool pulls from the PyPI JSON API."""

    name: str
    version: str
    summary: str | None
    requires_python: str | None


class PackageReport(BaseModel):
    """The agent's typed verdict on a PyPI package."""

    name: str
    latest_version: str
    summary: str
    recommendation: str


async def fetch_pypi_metadata(name: str) -> PackageFacts:
    """Fetch a package's metadata from the PyPI JSON API."""
    async with impit.AsyncClient(
        browser='firefox', follow_redirects=True, timeout=30
    ) as client:
        response = await client.get(PYPI_JSON_URL.format(name=name))

    if response.status_code != HTTPStatus.OK:
        raise RuntimeError(f'PyPI has no package named "{name}".')

    info = response.json()['info']
    return PackageFacts(
        name=info['name'],
        version=info['version'],
        summary=info['summary'],
        requires_python=info['requires_python'],
    )


async def main() -> None:
    async with Actor:
        # Parse the Actor input into the typed model, filling in defaults.
        actor_input = ActorInput.model_validate(await Actor.get_input() or {})
        package = actor_input.package
        model = actor_input.model

        # Route the LLM through the Apify OpenRouter proxy (no provider key needed).
        provider = OpenAIProvider(
            base_url=OPENROUTER_BASE_URL,
            api_key=os.environ['APIFY_TOKEN'],
        )

        # `output_type` makes the agent return a validated `PackageReport`. Passing
        # `fetch_pypi_metadata` in `tools` registers it as a tool from its signature.
        agent = Agent(
            OpenAIChatModel(model, provider=provider),
            output_type=PackageReport,
            tools=[fetch_pypi_metadata],
            system_prompt=(
                'You advise Python developers on packages. Always call '
                '`fetch_pypi_metadata` for facts instead of guessing.'
            ),
        )

        prompt = f'Evaluate the "{package}" package and recommend whether to use it.'
        report = (await agent.run(user_prompt=prompt)).output
        Actor.log.info(f'Package report:\n{report.model_dump_json(indent=2)}')
        await Actor.push_data(report.model_dump())


if __name__ == '__main__':
    asyncio.run(main())

Note that:

• The agent reaches the LLM through the Apify OpenRouter proxy via OpenAIChatModel and a custom OpenAIProvider, so no provider API key is needed.
• Passing fetch_pypi_metadata in the tools list registers it as a tool. PydanticAI builds its schema from the function's signature and docstring, and the agent calls it to fetch real facts instead of guessing. Returning a typed PackageFacts keeps the data validated on its way back to the agent.
• output_type=PackageReport makes the agent return a validated PackageReport, which maps directly onto a dataset row. To get plain text back, set output_type=str.

LlamaIndex

LlamaIndex is built for retrieval-augmented agents that reason over your own data. It indexes your documents into a vector store, retrieves the passages relevant to a question, and grounds the answer in them. It's a strong fit for question answering over private or domain-specific content. To install it, use:

pip install \
    llama-index \
    llama-index-llms-openai-like \
    llama-index-embeddings-huggingface \
    pydantic

The install also includes Pydantic for the Actor's typed input and output models.

The following Actor builds a retrieval-augmented generation (RAG) pipeline. It scrapes a few pages with the Website Content Crawler Actor via Actor.call, wraps each crawled page in a Document, indexes the documents in a vector store, answers a question using only the retrieved passages, and cites its sources:

Run on

import asyncio
import os

from llama_index.core import Document, VectorStoreIndex
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.llms.openai_like import OpenAILike
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'


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]


async def scrape_documents(urls: list[str]) -> list[Document]:
    """Scrape the pages with the Website Content Crawler and wrap them as `Document`s."""
    run_input = {'startUrls': [{'url': url} for url in urls], 'maxCrawlDepth': 0}
    run = await Actor.call('apify/website-content-crawler', run_input=run_input)
    dataset = Actor.apify_client.dataset(run.default_dataset_id)
    items = (await dataset.list_items()).items
    return [Document(text=item['text'], metadata={'url': item['url']}) for item in items]


async def main() -> None:
    async with Actor:
        # 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).
        llm = OpenAILike(
            model=model,
            api_base=OPENROUTER_BASE_URL,
            api_key=os.environ['APIFY_TOKEN'],
            is_chat_model=True,
        )

        # Embeddings run locally, so the proxy needs no embeddings endpoint. Loading the
        # model blocks, so offload it with `asyncio.to_thread`.
        embed_model = await asyncio.to_thread(
            HuggingFaceEmbedding, model_name=EMBED_MODEL
        )

        # Scrape the pages and wrap each result as a `Document` for the vector index.
        documents = await scrape_documents(urls)

        # Chunking and embedding every document blocks too, so offload it the same way.
        index = await asyncio.to_thread(
            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)

        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__':
    asyncio.run(main())

Note that:

• OpenAILike points api_base at the Apify OpenRouter proxy, so no provider API key is needed. It's the LlamaIndex LLM class for any OpenAI-compatible endpoint.
• Document wraps each scraped page, and VectorStoreIndex.from_documents chunks and embeds them. The index is the retrieval layer that sets LlamaIndex apart from a plain agent loop.
• Embeddings run locally through HuggingFaceEmbedding from the llama-index-embeddings-huggingface package, so the proxy needs no embeddings endpoint.
• The embedding model downloads on the first run and the Website Content Crawler renders pages in a browser, so this pipeline is heavier than the other examples.
• index.as_query_engine(output_cls=Answer) retrieves the passages most relevant to the question, then the LLM composes a validated Answer grounded in them.
• Every response carries the passages it used in response.source_nodes, so the Actor pushes their url metadata as citations. Actor.call runs the Website Content Crawler, and to_document maps each dataset item to a Document, so indexing more content is a matter of crawling more pages. For details, see Using Apify Actors as tools.

Smolagents

Smolagents is a lightweight framework whose agents write and run Python code to solve a task, instead of emitting structured tool calls. Writing code lets the agent chain several operations, loop, and transform data in a single step. It's a good fit for tasks that map cleanly to code. To install it, use:

pip install "smolagents[openai]" pydantic impit

The install also includes Pydantic for the Actor's typed input and output models, plus Impit, the HTTP client the Actor uses to call external APIs.

The following Actor runs a CodeAgent that writes Python to analyze the Hacker News front page. Its fetch_front_page tool uses Impit to call the Hacker News API, then the agent groups the stories by domain and returns a structured breakdown of the busiest ones:

Run on

import asyncio
import os

import impit
from pydantic import BaseModel, ValidationError
from smolagents import CodeAgent, OpenAIServerModel, tool

from apify import Actor

OPENROUTER_BASE_URL = 'https://openrouter.apify.actor/api/v1'
HN_FRONT_PAGE_URL = 'https://hn.algolia.com/api/v1/search?tags=front_page&hitsPerPage=50'
TOP_DOMAINS = 5


class ActorInput(BaseModel):
    """The Actor input, validated with default values."""

    model: str = 'openai/gpt-5.4-mini'


class DomainStat(BaseModel):
    """One domain's slice of the Hacker News front page."""

    domain: str
    story_count: int
    average_points: float


class FrontPageReport(BaseModel):
    """The structured analysis the agent computes from the front page."""

    total_stories: int
    top_domains: list[DomainStat]


@tool
def fetch_front_page() -> list[dict]:
    """Fetch the Hacker News front page as story dicts with title, url, and points."""
    with impit.Client(browser='firefox', follow_redirects=True, timeout=30) as client:
        hits = client.get(HN_FRONT_PAGE_URL).json()['hits']

    return [
        {'title': hit['title'], 'url': hit['url'], 'points': hit['points']}
        for hit in hits
        if hit.get('url') and hit.get('points') is not None
    ]


def is_valid_report(final_answer: object, *_: object, **__: object) -> bool:
    """Check the agent's answer against `FrontPageReport` so the schema is enforced."""
    try:
        FrontPageReport.model_validate(final_answer)
    except ValidationError:
        return False
    return True


async def main() -> None:
    async with Actor:
        # Parse the Actor input into the typed model, filling in defaults.
        actor_input = ActorInput.model_validate(await Actor.get_input() or {})
        model = actor_input.model

        # Route the LLM through the Apify OpenRouter proxy (no provider key needed).
        llm = OpenAIServerModel(
            model_id=model,
            api_base=OPENROUTER_BASE_URL,
            api_key=os.environ['APIFY_TOKEN'],
        )

        # A `CodeAgent` solves the task by writing and running Python, so it groups
        # and averages the stories in code. `final_answer_checks` re-runs
        # `is_valid_report` on each answer until the output validates.
        agent = CodeAgent(
            tools=[fetch_front_page],
            model=llm,
            additional_authorized_imports=['collections', 'statistics', 'urllib.parse'],
            final_answer_checks=[is_valid_report],
        )

        prompt = (
            'Analyze the current Hacker News front page. Call `fetch_front_page`, '
            'then use code to take the domain of each story URL, group the stories '
            f'by domain, and find the {TOP_DOMAINS} domains with the most stories. '
            'Call `final_answer` with a dict shaped like {"total_stories": int, '
            '"top_domains": [{"domain": str, "story_count": int, '
            '"average_points": float}]}.'
        )
        # `CodeAgent.run` is synchronous, so `asyncio.to_thread` keeps it off the
        # Actor's event loop.
        result = await asyncio.to_thread(agent.run, prompt)

        report = FrontPageReport.model_validate(result)
        Actor.log.info(f'Front page report:\n{report.model_dump_json(indent=2)}')
        await Actor.push_data(report.model_dump())


if __name__ == '__main__':
    asyncio.run(main())

Note that:

• OpenAIServerModel points api_base at the Apify OpenRouter proxy, so no provider API key is needed.
• Writing code is what a CodeAgent does best. It calls fetch_front_page, then writes Python to take each URL's domain, group the stories, and average their points. additional_authorized_imports grants the standard-library modules that code needs.
• final_answer_checks validates every candidate answer against FrontPageReport. A mismatch sends the agent back to fix its code, so the output stays structured rather than free-form. The returned dict is then parsed with FrontPageReport.model_validate.
• CodeAgent.run is synchronous, so asyncio.to_thread runs it without blocking the Actor's event loop.
• Because a CodeAgent executes the code it generates, run it in the isolated Actor container rather than on your own machine.

Using Apify Actors as tools

An agent becomes useful once it can act on the world. On Apify, any of the thousands of Actors in Apify Store can become a tool: a scraper that fetches data, a browser automation that fills a form, or an API wrapper that posts a message.

Some frameworks ship a ready-made wrapper for turning an Actor into a tool. For LangGraph and other LangChain-based agents, the langchain-apify package exposes any Actor as a tool with a single line:

from langchain_apify import ApifyActorsTool

# Let the agent scrape Instagram profiles by calling the apify/instagram-scraper Actor.
tools = [ApifyActorsTool('apify/instagram-scraper')]

For any other framework, call the Actor with Actor.call and read its dataset through the preconfigured API client:

async def scrape_instagram(handle: str) -> list[dict]:
    """Scrape recent posts from an Instagram profile."""
    run_input = {'directUrls': [f'https://www.instagram.com/{handle}/']}
    run = await Actor.call('apify/instagram-scraper', run_input=run_input)
    return (await Actor.apify_client.dataset(run.default_dataset_id).list_items()).items

The CrewAI example wraps this pattern in a BaseTool so its agent can call the Actor.

For details on calling other Actors, see Interacting with other Actors.

Running on the Apify platform

Agents run on the standard Apify Python base image, so no browser or extra system dependencies are needed. Add apify and the packages required by your framework to requirements.txt, then deploy the Actor as usual.

To monetize the agent, use pay-per-event charging. You define events such as task-completed in the Actor's monetization settings and trigger them from the code:

await Actor.charge('task-completed')

This approach lets you charge users directly from the Actor and cover the cost of execution and LLM tokens. It pairs well with the Apify OpenRouter proxy, which already bills the LLM usage to the account running the Actor.

Conclusion

In this guide, you learned how to host an AI agent as an Apify Actor. You can now build an agent with LangGraph, CrewAI, PydanticAI, LlamaIndex, or Smolagents, connect it to an LLM through the Apify OpenRouter proxy, give it Apify Actors as tools, and monetize it with pay-per-event. To get started, see the Actor templates. If you have questions or need assistance, feel free to reach out on our GitHub or join our Discord community. Happy building!

Additional resources

• Apify: LangGraph template
• Apify: CrewAI template
• Apify: PydanticAI template
• Apify: LlamaIndex template
• Apify: Smolagents template
• Apify: actor-templates repository
• Apify: OpenRouter proxy
• Apify: langchain-apify integration
• Apify blog: What are AI agents