docs: add AI agents guide#995
Open
vdusek wants to merge 6 commits into
Open
Conversation
vdusek
added
adhoc
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #995 +/- ##
==========================================
- Coverage 91.72% 91.69% -0.03%
==========================================
Files 50 50
Lines 3213 3215 +2
==========================================
+ Hits 2947 2948 +1
- Misses 266 267 +1
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
vdusek
force-pushed
the
docs/ai-agents-guide
branch
2 times, most recently
from
84b618c to
1bb3288
Compare
vdusek
force-pushed
the
docs/ai-agents-guide
branch
from
1bb3288 to
034a077
Compare
szaganek
approved these changes
Jul 6, 2026
|
|
||
| Apify Actors are a natural home for agents: | ||
|
|
||
| - An agent is just a Python program, so wrapping it in `async with Actor:` is all it takes to run it on the platform. |
Contributor
There was a problem hiding this comment.
Suggested change
| - An agent is just a Python program, so wrapping it in `async with Actor:` is all it takes to run it on the platform. | |
| - An agent is just a Python program, so wrap it in `async with Actor:` to run it on the platform. |
|
|
||
| - An agent is just a Python program, so wrapping it in `async with Actor:` is all it takes to run it on the platform. | ||
| - The platform scales runs, schedules them, and keeps logs, so you don't operate any infrastructure yourself. | ||
| - The [Apify Store](https://apify.com/store) gives your agent thousands of ready-made tools. Any Actor (a scraper, a browser automation, an API wrapper) can become a tool the agent calls. |
Contributor
There was a problem hiding this comment.
Suggested change
| - The [Apify Store](https://apify.com/store) gives your agent thousands of ready-made tools. Any Actor (a scraper, a browser automation, an API wrapper) can become a tool the agent calls. | |
| - [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. |
|
|
||
| ## 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. Pick the one that matches the framework you already use, or the style of agent you want to build: |
Contributor
There was a problem hiding this comment.
Suggested change
| 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. Pick the one that matches the framework you already use, or the style of agent you want to build: | |
| 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. |
| | [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), and you can scaffold any of them with the [Apify CLI](https://docs.apify.com/cli), for example `apify create my-agent --template python-pydanticai`. |
Contributor
There was a problem hiding this comment.
Suggested change
| All of these templates live in the [actor-templates repository](https://github.com/apify/actor-templates), and you can scaffold any of them with the [Apify CLI](https://docs.apify.com/cli), for example `apify create my-agent --template python-pydanticai`. | |
| 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: | |
| /```apify create my-agent --template python-pydanticai``` |
| | 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) | |
Contributor
There was a problem hiding this comment.
Suggested change
| | [CrewAI](#crewai) | Multi-agent "crews" that collaborate on a task | [`python-crewai`](https://apify.com/templates/python-crewai) | | |
| | [CrewAI](#crewai) | Multi-agent “crews” that collaborate on a task | [`python-crewai`](https://apify.com/templates/python-crewai) | |
|
|
||
| - `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` (see [Using Apify Actors as tools](#using-apify-actors-as-tools)), as the [LlamaIndex template](https://apify.com/templates/python-llamaindex-agent) does with a contact-details scraper. |
Contributor
There was a problem hiding this comment.
Suggested change
| - To reason over your own data, wrap an Apify Actor in a `FunctionTool` (see [Using Apify Actors as tools](#using-apify-actors-as-tools)), as the [LlamaIndex template](https://apify.com/templates/python-llamaindex-agent) does with a contact-details scraper. | |
| - 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). |
|
|
||
| ## 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 the [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. |
Contributor
There was a problem hiding this comment.
Suggested change
| An agent becomes useful once it can act on the world. On Apify, any of the thousands of Actors in the [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. | |
| 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. |
|
|
||
| An agent becomes useful once it can act on the world. On Apify, any of the thousands of Actors in the [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 this. 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: |
Contributor
There was a problem hiding this comment.
We can't leave a single this dangling like that, we need to specify what this is.
|
|
||
| ## 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 shown in your framework's section above to `requirements.txt`, then deploy the Actor as usual. |
Contributor
There was a problem hiding this comment.
Suggested change
| 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 shown in your framework's section above to `requirements.txt`, then deploy the Actor as usual. | |
| 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. |
Please verify my guess. I honestly don't know what section it refers to.
| await Actor.charge('task-completed') | ||
| ``` | ||
|
|
||
| This 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. |
Contributor
There was a problem hiding this comment.
Suggested change
| This 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. | |
| 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. |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
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.
Add a guide on hosting AI agents as Apify Actors.
Each of the five supported frameworks (LangGraph, CrewAI, PydanticAI, LlamaIndex, and Smolagents) gets a complete, runnable single-file Actor example. Every example routes its LLM calls through the Apify OpenRouter proxy, so no provider API key is needed and each one runs as a "Run on Apify" example. The guide also covers choosing a framework, connecting to an LLM, using Apify Actors as agent tools, and monetizing with pay-per-event. Every framework links to its matching Actor template.
The new guide is also linked from the README, the overview, and the quick start.