Skip to content

Commit d953ef2

Browse files
IremOztimurmarcel-rbroclaude
authored
docs: add Upsonic integration documentation (#2350)
## Summary - Adds integration guide for [Upsonic](https://upsonic.ai), an open-source Python framework for building AI agents - Covers basic setup with `ApifyTools` and an advanced restaurant discovery agent example using Google Places Crawler - Documents all `ApifyTools` configuration options with types and defaults --------- Co-authored-by: Marcel Rebro <marcel.rebro@apify.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent a9a91de commit d953ef2

File tree

1 file changed

+166
-0
lines changed

1 file changed

+166
-0
lines changed

‎sources/platform/integrations/ai/upsonic.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
title: Upsonic integration
3+
sidebar_label: Upsonic
4+
description: Learn how to integrate Apify Actors with Upsonic to give your AI agents real-time web scraping, data extraction, and automation capabilities from the Apify Store.
5+
sidebar_position: 20
6+
slug: /integrations/upsonic
7+
---
8+
9+
import ThirdPartyDisclaimer from '@site/sources/_partials/_third-party-integration.mdx';
10+
11+
## What is Upsonic
12+
13+
[Upsonic](https://upsonic.ai) is an open-source Python framework for building AI agents. It supports any LLM (e.g., OpenAI, Anthropic, Azure, and Bedrock) and provides:
14+
15+
- An `AutonomousAgent` class with built-in shell and filesystem access
16+
- A safety engine for policy-based content filtering
17+
- Built-in OCR and document processing
18+
- Session and long-term memory
19+
- Multi-agent coordination and MCP server support
20+
- [Universal Commerce Protocol (UCP)](https://github.com/Upsonic/awesome-ucp) tools for AI-driven commerce workflows
21+
22+
See the [Upsonic documentation](https://docs.upsonic.ai) for more details on building AI agents.
23+
24+
<ThirdPartyDisclaimer />
25+
26+
## How to use Apify with Upsonic
27+
28+
This guide shows how to integrate Apify Actors with Upsonic using the built-in `ApifyTools` class. The example builds a restaurant discovery agent that uses the [Google Places Crawler](https://apify.com/compass/crawler-google-places) Actor to search Google Maps with a natural language query. It saves the results to a Markdown file.
29+
30+
### Prerequisites
31+
32+
- Apify API token: Obtain your API token from the [Apify Console](https://console.apify.com/account/integrations).
33+
- Anthropic API key (or another LLM provider): Get one from the [Anthropic Console](https://console.anthropic.com).
34+
- Python environment: Python 3.9 or later.
35+
- Required packages: Install the following dependencies:
36+
37+
```bash
38+
pip install 'upsonic[custom-tools]' python-dotenv apify-client anthropic
39+
```
40+
41+
:::tip Alternative LLM providers
42+
43+
Upsonic uses LiteLLM under the hood. Swap `anthropic/claude-sonnet-4-6` for any supported model string, e.g. `openai/gpt-4o` or `gemini-3-flash-preview`. Update the environment variable and model name accordingly.
44+
45+
:::
46+
47+
## Basic integration example
48+
49+
Set up an Upsonic agent with Apify tools. This example uses the [RAG Web Browser](https://apify.com/apify/rag-web-browser) Actor to extract content from a URL.
50+
51+
```python
52+
import os
53+
from upsonic import Agent, Task
54+
from upsonic.tools.custom_tools.apify import ApifyTools
55+
56+
agent = Agent(
57+
"anthropic/claude-sonnet-4-6",
58+
tools=[
59+
ApifyTools(
60+
actors=["apify/rag-web-browser"],
61+
apify_api_token=os.getenv("APIFY_API_TOKEN"),
62+
)
63+
],
64+
)
65+
66+
task = Task("What information can you find on https://docs.apify.com/platform/actors?")
67+
agent.print_do(task)
68+
```
69+
70+
Running this code fetches and summarizes the content from the provided URL.
71+
72+
## Advanced scenario: Restaurant discovery agent
73+
74+
Combine `ApifyTools` with the Google Places Crawler to build an agent that accepts a natural language query and returns a list of matching restaurants.
75+
76+
`actor_defaults` pre-sets configuration that never needs to change - such as result limits and output format - while leaving the search query under the LLM's control. The `timeout` override is necessary because the Actor takes 60-90 seconds to crawl Google Maps.
77+
78+
```python
79+
import os
80+
from upsonic import Agent, Task
81+
from upsonic.tools.custom_tools.apify import ApifyTools
82+
from dotenv import load_dotenv
83+
84+
load_dotenv()
85+
86+
agent = Agent(
87+
"anthropic/claude-sonnet-4-6",
88+
tools=[
89+
ApifyTools(
90+
actors=["compass/crawler-google-places"],
91+
apify_api_token=os.getenv("APIFY_API_TOKEN"),
92+
actor_defaults={
93+
"compass/crawler-google-places": {
94+
"maxCrawledPlacesPerSearch": 10,
95+
"maxImages": 0,
96+
"outputFormats": ["markdown"],
97+
}
98+
},
99+
timeout=180.0,
100+
max_retries=0,
101+
)
102+
],
103+
)
104+
105+
task = Task("Find cheap and tasty falafel places in Kadikoy, Istanbul")
106+
agent.print_do(task)
107+
108+
with open("results.md", "w") as f:
109+
f.write(task.response)
110+
111+
print("Results saved to results.md")
112+
```
113+
114+
The agent interprets the natural language query, calls the Actor with appropriate search parameters, and formats the response:
115+
116+
```markdown
117+
## Best cheap and tasty falafel places in Kadikoy
118+
119+
### 1. Falafella - 4.3/5
120+
- Price: very affordable
121+
- Address: Caferaga, Moda Cd. No:53A, Kadikoy
122+
- Hours: 11 AM - 2 AM
123+
- Vegan options available
124+
125+
### 2. Nohut Falafel & Humus - 4.8/5
126+
- Address: Osmanaga, Sakiz Sk. No:22C, Kadikoy
127+
- Hours: 12 PM - 10 PM
128+
- Gluten-free and vegan, known for fresh ingredients
129+
```
130+
131+
:::note Crawl time
132+
133+
Each run takes 60-90 seconds as the Actor crawls Google Maps. Keep `maxCrawledPlacesPerSearch` at 10 or below - more results can exceed the model's context limit.
134+
135+
:::
136+
137+
## Configuration options
138+
139+
`actors` (string or `List[string]`, default: `None`)
140+
: Single Actor ID or list of Actor IDs to register as tools.
141+
142+
`apify_api_token` (string, default: `None`)
143+
: Apify API token. Falls back to the `APIFY_API_TOKEN` environment variable.
144+
145+
`actor_defaults` (`Dict[string, Dict[string, Any]]`, default: `None`)
146+
: Per-actor default input values. Keys are Actor IDs, values are dicts of parameter to value. Hidden from the LLM and merged at call time.
147+
148+
`timeout` (float, default: `30.0`)
149+
: Maximum seconds to wait for the Actor run to finish.
150+
151+
`max_retries` (int, default: `3`)
152+
: Number of retry attempts on failure. Set to `0` to prevent parallel duplicate runs on timeout.
153+
154+
:::tip Apify Store
155+
156+
Browse the [Apify Store](https://apify.com/store) to find Actors for social media scraping, e-commerce data extraction, news aggregation, and more. Pass any Actor ID to `actors` to use it immediately.
157+
158+
:::
159+
160+
## Resources
161+
162+
- [Upsonic documentation](https://docs.upsonic.ai)
163+
- [Upsonic ApifyTools reference](https://docs.upsonic.ai/concepts/tools/scraping-tools/apify)
164+
- [Upsonic restaurant scout example](https://github.com/Upsonic/Examples/tree/master/examples/web_search_and_scraping/apify_google_maps_restaurant_scout)
165+
- [Apify Actor documentation](/platform/actors)
166+
- [Browse Actors on Apify Store](https://apify.com/store)

0 commit comments

Comments
 (0)