-
Notifications
You must be signed in to change notification settings - Fork 26
docs: add AI agents guide #995
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
vdusek
wants to merge
8
commits into
master
Choose a base branch
from
docs/ai-agents-guide
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
7c15f48
docs: add AI agents guide
vdusek 034a077
docs: split AI agents guide into per-framework sections
vdusek 622a720
docs: align AI agents guide examples with their Actor templates
vdusek 817d0e0
docs: refine AI agents guide and renumber to 14
vdusek 2409633
docs: route the CrewAI agent example through the OpenRouter proxy
vdusek 2fa02f9
docs: align AI agent template order in README and introduction with t…
vdusek c145723
Merge remote-tracking branch 'origin/master' into docs/ai-agents-guide
vdusek fd91257
docs: address review comments on the AI agents guide
vdusek File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,209 @@ | ||
| --- | ||
| id: ai-agents | ||
| title: Hosting AI agents | ||
| description: Host AI agents built with LangGraph, CrewAI, PydanticAI, LlamaIndex, or Smolagents as Apify Actors. | ||
| --- | ||
|
|
||
| import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock'; | ||
|
|
||
| import LanggraphExample from '!!raw-loader!roa-loader!./code/14_langgraph.py'; | ||
| import CrewaiExample from '!!raw-loader!roa-loader!./code/14_crewai.py'; | ||
| import PydanticaiExample from '!!raw-loader!roa-loader!./code/14_pydanticai.py'; | ||
| import LlamaindexExample from '!!raw-loader!roa-loader!./code/14_llamaindex.py'; | ||
| import SmolagentsExample from '!!raw-loader!roa-loader!./code/14_smolagents.py'; | ||
|
|
||
| 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 a natural home for agents: | ||
|
|
||
| - An agent is just a Python program, so wrap it in `async with Actor:` to run it on the platform. | ||
| - The platform scales runs, schedules them, and keeps logs, so you don't operate any infrastructure yourself. | ||
| - [Apify Store](https://apify.com/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](https://apify.com/apify/openrouter) lets the agent talk to an LLM without managing a provider API key. | ||
| - 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. | ||
|
|
||
| ## 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](#langgraph) | Graph-based agents with explicit state and control flow | [`python-langgraph`](https://apify.com/templates/python-langgraph) | | ||
| | [CrewAI](#crewai) | Multi-agent "crews" that collaborate on a task | [`python-crewai`](https://apify.com/templates/python-crewai) | | ||
| | [PydanticAI](#pydanticai) | Typed, Pydantic-native agents with tool calling | [`python-pydanticai`](https://apify.com/templates/python-pydanticai) | | ||
| | [LlamaIndex](#llamaindex) | Retrieval-augmented agents over your own data | [`python-llamaindex-agent`](https://apify.com/templates/python-llamaindex-agent) | | ||
| | [Smolagents](#smolagents) | Lightweight code-writing agents | [`python-smolagents`](https://apify.com/templates/python-smolagents) | | ||
|
|
||
| All of these templates live in the [actor-templates repository](https://github.com/apify/actor-templates). To create a project, use the [Apify CLI](https://docs.apify.com/cli), for example: | ||
|
|
||
| ```bash | ||
| apify create my-agent --template python-pydanticai | ||
| ``` | ||
|
|
||
| ## Connecting to an LLM | ||
|
|
||
| There are two ways to provide an agent with an LLM: | ||
|
|
||
| - Use [Apify OpenRouter proxy](https://apify.com/apify/openrouter), an OpenAI-compatible endpoint at `https://openrouter.apify.actor/api/v1` that fronts the full [OpenRouter](https://openrouter.ai) model catalog. 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. Any framework with an OpenAI-compatible client can point its base URL at the proxy, which is what every example in this guide does. To switch models, change the `model` input to any [OpenRouter model slug](https://openrouter.ai/models), for example `openai/gpt-4o-mini`. | ||
| - 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](https://docs.apify.com/platform/actors/development/programming-interface/environment-variables) and locally you export in your shell. | ||
|
|
||
| ## LangGraph | ||
|
|
||
| [LangGraph](https://www.langchain.com/langgraph) builds an agent as a graph with explicit state, which makes complex, multi-step control flow easy to follow. It builds on [LangChain](https://www.langchain.com/), so any LangChain chat model and tool works. To install it, use: | ||
|
|
||
| ```bash | ||
| pip install langchain langchain-openai langgraph | ||
| ``` | ||
|
|
||
| The following Actor runs an agent with a single tool: | ||
|
|
||
| <RunnableCodeBlock className="language-python" language="python"> | ||
| {LanggraphExample} | ||
| </RunnableCodeBlock> | ||
|
|
||
| Note that: | ||
|
|
||
| - `ChatOpenAI` points its `base_url` at the Apify OpenRouter proxy, so any LangChain chat model works without a provider key. | ||
| - The agent decides on its own when to call the `sum_numbers` tool, and the answer is read from the last message in the returned state. | ||
| - To extend this agent, add more LangChain tools, including Apify Actors. For details, see [Using Apify Actors as tools](#using-apify-actors-as-tools). | ||
|
|
||
| ## CrewAI | ||
|
|
||
| [CrewAI](https://www.crewai.com/) models a problem as a "crew" of role-playing agents that work through tasks. To install it, use: | ||
|
vdusek marked this conversation as resolved.
|
||
|
|
||
| ```bash | ||
| pip install crewai | ||
| ``` | ||
|
|
||
| The following Actor defines a single analyst agent with one tool: | ||
|
|
||
| <RunnableCodeBlock className="language-python" language="python"> | ||
| {CrewaiExample} | ||
| </RunnableCodeBlock> | ||
|
|
||
| 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. | ||
| - `kickoff_async` runs the crew without blocking the Actor's event loop. | ||
| - The agent decides on its own when to call the `average` tool. Add more tools to extend it, including Apify Actors. For details, see [Using Apify Actors as tools](#using-apify-actors-as-tools). | ||
| - 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](https://ai.pydantic.dev/) is an agent framework from the team behind Pydantic. It's strongly typed and integrates naturally with the [Pydantic models](./input-validation) the Apify SDK already uses. To install it, use: | ||
|
|
||
| ```bash | ||
| pip install pydantic-ai | ||
| ``` | ||
|
|
||
| The following Actor generates a joke and returns it as a typed object: | ||
|
|
||
| <RunnableCodeBlock className="language-python" language="python"> | ||
| {PydanticaiExample} | ||
| </RunnableCodeBlock> | ||
|
|
||
| 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. | ||
| - `output_type=Joke` makes the agent return a validated `Joke` instance, which maps directly onto a dataset row. To get plain text back, set `output_type=str`. | ||
|
|
||
| ## LlamaIndex | ||
|
|
||
| [LlamaIndex](https://www.llamaindex.ai/) is built for retrieval-augmented agents that reason over your own data. To install it, use: | ||
|
|
||
| ```bash | ||
| pip install llama-index llama-index-llms-openai-like | ||
| ``` | ||
|
|
||
| The following Actor runs a `ReActAgent` with a single tool: | ||
|
|
||
| <RunnableCodeBlock className="language-python" language="python"> | ||
| {LlamaindexExample} | ||
| </RunnableCodeBlock> | ||
|
|
||
| Note that: | ||
|
|
||
| - `OpenAILike` is the LlamaIndex LLM class for OpenAI-compatible endpoints such as the Apify OpenRouter proxy. It needs the `llama-index-llms-openai-like` package. | ||
| - The agent decides on its own when to call the `word_count` tool. Add `FunctionTool`s of your own to extend it. | ||
| - To reason over your own data, wrap an Apify Actor in a `FunctionTool`, as the [LlamaIndex template](https://apify.com/templates/python-llamaindex-agent) does with a contact-details scraper. See also [Using Apify Actors as tools](#using-apify-actors-as-tools). | ||
|
|
||
| ## Smolagents | ||
|
|
||
| [Smolagents](https://github.com/huggingface/smolagents) is a lightweight framework from Hugging Face whose agents write and run Python code to solve a task. To install it, use: | ||
|
|
||
| ```bash | ||
| pip install "smolagents[openai]" | ||
| ``` | ||
|
|
||
| The following Actor runs a `CodeAgent`: | ||
|
|
||
| <RunnableCodeBlock className="language-python" language="python"> | ||
| {SmolagentsExample} | ||
| </RunnableCodeBlock> | ||
|
|
||
| Note that: | ||
|
|
||
| - `OpenAIServerModel` points `api_base` at the Apify OpenRouter proxy, so no provider API key is needed. | ||
| - The agent uses `WebSearchTool` to fetch the latest news, then writes and runs Python code to summarize it. | ||
| - 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](https://apify.com/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](https://www.langchain.com/)-based agents, the [`langchain-apify`](https://github.com/apify/langchain-apify) package exposes any Actor as a tool with a single line: | ||
|
|
||
| ```python | ||
| from langchain_apify import ApifyActorsTool | ||
|
|
||
| # Let the agent scrape Instagram profiles by calling the apify/instagram-scraper Actor. | ||
| tools = [ApifyActorsTool('apify/instagram-scraper')] | ||
| ``` | ||
|
|
||
| CrewAI ships the same tool as `crewai_tools.ApifyActorsTool` in its `crewai[tools]` package. | ||
|
|
||
| For any other framework, call the Actor directly through the Actor's preconfigured API client and read its dataset: | ||
|
|
||
| ```python | ||
| 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.apify_client.actor('apify/instagram-scraper').call(run_input=run_input) | ||
| return (await Actor.apify_client.dataset(run['defaultDatasetId']).list_items()).items | ||
| ``` | ||
|
|
||
| For details on calling other Actors, see [Interacting with other Actors](../concepts/interacting-with-other-actors). | ||
|
|
||
| ## Running on the Apify platform | ||
|
|
||
| Agents run on the standard [Apify Python base image](https://hub.docker.com/r/apify/actor-python), 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](../concepts/pay-per-event). You define events such as `task-completed` in the Actor's monetization settings and trigger them from the code: | ||
|
|
||
| ```python | ||
| 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 naturally 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](https://apify.com/templates/categories/python). If you have questions or need assistance, feel free to reach out on our [GitHub](https://github.com/apify/apify-sdk-python) or join our [Discord community](https://discord.com/invite/jyEM2PRvMU). Happy building! | ||
|
|
||
| ## Additional resources | ||
|
|
||
| - [Apify: LangGraph template](https://apify.com/templates/python-langgraph) | ||
| - [Apify: CrewAI template](https://apify.com/templates/python-crewai) | ||
| - [Apify: PydanticAI template](https://apify.com/templates/python-pydanticai) | ||
| - [Apify: LlamaIndex template](https://apify.com/templates/python-llamaindex-agent) | ||
| - [Apify: Smolagents template](https://apify.com/templates/python-smolagents) | ||
| - [Apify: actor-templates repository](https://github.com/apify/actor-templates) | ||
| - [Apify: OpenRouter proxy](https://apify.com/apify/openrouter) | ||
| - [Apify: langchain-apify integration](https://github.com/apify/langchain-apify) | ||
| - [Apify blog: What are AI agents](https://blog.apify.com/what-are-ai-agents/) | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.