diff --git a/README.md b/README.md index 5b05bb7f..7761c0ed 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,12 @@
License - - - Downloads GitHub last commit + +GitHub Actions Status + Python Version @@ -33,17 +33,16 @@

- Docs • - Toolkits • - Model Providers • - Auth Providers • - Examples + Documentation • + Tools • + Quickstart • + Contact Us -## What is Arcade? +# Arcade Tool SDK -[Arcade](https://arcade.dev?ref=github) provides developer-focused tooling and APIs designed to improve the capabilities of LLM applications and agents. +Arcade is a developer platform that lets you build, deploy, and manage tools for AI agents. -By removing the complexity of connecting agentic applications with your users' data and services, Arcade enables developers to focus on building their agentic applications. +The Tool SDK makes it easy to create powerful, secure tools that your agents can use to interact with the world. To learn more, check out our [documentation](https://docs.arcade.dev/home). @@ -53,273 +52,516 @@ _Pst. hey, you, give us a star if you like it!_ GitHub stars -## Quickstart +## Table of Contents -### Requirements +- [The Problems with Agent Tools](#the-problems-with-agent-tools) +- [Without Arcade vs. With Arcade](#without-arcade-vs-with-arcade) +- [Why Build Tools with Arcade?](#why-build-tools-with-arcade) +- [Quickstart: Call your first tool](#quickstart-call-your-first-tool) +- [Building Your Own Tools](#building-your-own-tools) + - [Tool SDK Installation](#tool-sdk-installation) + - [Creating a New Tool](#creating-a-new-tool) + - [Sharing Your Toolkit](#sharing-your-toolkit) +- [Calling your tools](#calling-your-tools) + - [LLM API](#llm-api) + - [Tools API](#tools-api) + - [Integrating with Agent Frameworks](#integrating-with-agent-frameworks) + - [Arcade Auth API](#arcade-auth-api) +- [Client Libraries](#client-libraries) +- [Support and Community](#support-and-community) -1. An **[Arcade account](https://account.arcade.dev/register?return_to=https%3A%2F%2Fapi.arcade.dev%2Fdashboard%2Fwelcome)** -2. **Python 3.10+** and **pip** +## The Problems with Agent Tools -### Installation +**The Auth Problem** +Most agent tools lack multi-user authorization capabilities. They typically rely on hardcoded API keys or environment variables, making it impossible to securely access user-specific data or integrate with services requiring user authentication and/or authorization. -Install the package: +**The Execution Problem** +Tool execution typically happens on the same resources as the agent, limiting scalability and preventing the use of specialized compute resources (serverless, on-premise, etc.). -```bash -pip install arcade-ai -``` +**The Tool Definition Problem** +Maintaining tool definitions separately from code is difficult, especially when tools must work across multiple agent applications and LLMs with different formats. -Log in to your account via the CLI: +Arcade solves these challenges with standardized tool definition and execution, a robust multi-user auth system, and flexible integration APIs. -```bash -arcade login -``` - -This opens a browser window for authentication. - -### Verify Installation with `arcade chat` - -Use the `arcade chat` CLI app to test tools: - -```bash -arcade chat -``` - -This connects to the Arcade Cloud Engine (`api.arcade.dev`) with all pre-built Arcade tools. - -For example, try: - -```text -User (dev@arcade.dev): -> star the ArcadeAI/arcade-ai repo on Github -``` - -Arcade will prompt you to authorize with GitHub and will star the [ArcadeAI/arcade-ai](https://github.com/ArcadeAI/arcade-ai) repo on your behalf. - -You'll see: - -```text -Assistant (gpt-4o): -I starred the ArcadeAI/arcade-ai repo on Github for you! -``` - -Press `Ctrl-C` to exit the chat. - -## Arcade Cloud - -Arcade Cloud is a hosted version of the Arcade engine that hosts a number of prebuilt toolkits for interacting with a variety of services. - -### Prebuilt Toolkits - -Arcade offers a number of prebuilt toolkits that can be used by agents to interact with a variety of services. +## Without Arcade vs. With Arcade - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + +
ServiceAuth TypeToolkitDocumentation
GitHubOAuthGithubGitHub Toolkit Docs
GmailOAuthGoogleGmail Toolkit Docs
Google CalendarOAuthGoogleGoogle Calendar Toolkit Docs
Google DocsOAuthGoogleGoogle Docs Toolkit Docs
Google DriveOAuthGoogleGoogle Drive Toolkit Docs
SearchAPI KeySearchSearch Toolkit Docs
SlackOAuthSlackSlack Toolkit Docs
SpotifyOAuthSpotifySpotify Toolkit Docs
WebAPI KeyWebWeb Toolkit Docs
TwitterOAuthXX Toolkit Docs
Without ArcadeWith Arcade
+ +```python +# Building a Gmail tool without Arcade +import os +from google.oauth2.credentials import Credentials +from googleapiclient.discovery import build + +def get_credentials(): + # Get credentials from environment variables + secret = os.environ["GMAIL_CREDENTIALS"] + # Always same token same user + # Usually we dangerously elevated privileges + token = os.environ["GMAIL_TOKEN"] + return secret, token + +# Define the tool in code, then update +# definition for each LLM +def list_emails(max_results=10): + + # Get credentials here? pass it in? + secret, token = get_credentials() + # Cache the token? + # How do we know the user? + + # What if the user isn't authorized? OAuth Flow? + # handle token refresh? + try: + credentials = Credentials( + token=token, + secret=secret) + except Exception as e: + # Start the OAuth flow? + # redirect ? how do we know the user? + # handle token refresh? + # what are the right scopes? + # handle errors? + # for EVERY SERVICE? + + # Call the API + service = build('gmail', 'v1', credentials=credentials) + + messages = service.users().messages().list( + userId='me', maxResults=max_results + ).execute() + + return messages + +# Problems: +# - Hardcoded credentials means no multi-user support +# - Security risks from exposing secrets/tokens/keys +# - Manual OAuth flow implementation, if any +# - Manually updated tool definitions +# - No standard format translated across LLMs +``` + + + +```python +# Building a Gmail tool with Arcade SDK + +from arcade.sdk import ToolContext, tool +from arcade.sdk.auth import Google +from google.oauth2.credentials import Credentials +from googleapiclient.discovery import build + + +# Define the tool in code, automatically generate +# tool definition for all LLMs +@tool( + requires_auth=Google( + scopes=["https://www.googleapis.com/auth/gmail.readonly"], + ) +) # Automatically generated tool definition from annotations +async def list_emails( + context: ToolContext, + max_results: Annotated[int, "Maximum emails to return"] = 10, +) -> Annotated[dict, "List of emails"]: + """Lists emails in the user's Gmail inbox.""" + + # Auth token automatically provided and managed by Arcade + # Token is guaranteed to be valid for the user of the agent + token = context.authorization.token + + # No need to manually refresh tokens or handle OAuth flows + # Credentials are automatically refreshed as needed + service = build('gmail', 'v1', credentials=token) + + messages = service.users().messages().list( + userId='me', maxResults=max_results + ).execute() + + return messages + +# Solutions with Arcade: +# - Multi-tenant (works for any user) +# - Compliant and secure token, secret, and key management +# - Can access any user's data or services AS the user +# - Tool definition is created automatically +# - Formatted for all LLMs and ready to use +``` + +
+## Why Build Tools with Arcade? + +Arcade solves key challenges for agent developers: + +1. **Auth Native to Agents**: Authentication designed for agentic workflows — the right token is always available for each user without complex integration work. + +2. **Multi-Tenant Tool Calling**: Enable your agent to take actions AS the specific user of the agent + +3. **Better Agent Capabilities**: Build tools that securely connect to the services your users want your agent to integrate with (Gmail, Slack, Google Drive, Zoom, etc.) without complex integration code. + +4. **Clean Codebase**: Eliminate environment variables full of API keys and complex OAuth implementations from your application code. + +5. **Flexible Integration**: Choose your integration approach: + + - LLM API for the simplest experience with hundreds of pre-built tools + - Tools API for direct execution control + - Auth API for authentication-only integration + - Framework connectors for LangChain, CrewAI and others + +6. **Zero Schema Maintenance**: Tool definitions generate automatically from code annotations and translate to any LLM format. + +7. **Built-in Evaluation**: Evaluate your tools across user scenarios, llms, and context with Arcade's tool calling evaluation framework. Ensure your tools are working as expected and are useful for your agents. + +8. **Complete Tooling Ecosystem**: Built-in evaluation framework, scalable execution infrastructure, and flexible deployment options (including VPC, Docker, and Kubernetes). + +Arcade lets you focus on creating useful tool functionality rather than solving complex authentication, deployment, and integration challenges. + +## Quickstart: Call your first tool + +```bash +# Install the Arcade CLI +pip install arcade-ai + +# Log in to Arcade +arcade login + +# Show what tools are hosted by Arcade +arcade show + +# show what tools are in a toolkit +arcade show -T Google + +# look at the definition of a tool +arcade show -t Google.ListEmails + +# Run Arcade Chat and call a tool +arcade chat -s +``` + +Ask the chat to + +- Read your latest email in gmail +- Find latest tweets by @tryarcade + +If Arcade already hosts the tools you need to build your agent, you +can navigate to the [Quickstart](https://docs.arcade.dev/home/quickstart) to +learn how to call tools programmatically in Python, Typescript, or HTTP. + +However, if not, you can start building your own tools and use them through Arcade +benefitting from all the same features (like auth) that the cloud hosted tools have. + +## Building Your Own Tools + +Arcade provides a tool SDK that allows you to build your own tools and use them in your agentic applications just like the existing tools Arcade provides. This is useful for building new tools, customizing existing tools to fit your needs, combining multiple tools, or building tools that are not yet supported by Arcade. + +### Tool SDK Installation + +**Prerequisites** + +- **Python 3.10+** +- **Arcade Account:** [Sign up here](https://api.arcade.dev/signup) to get started. + +Now you can install the Tool SDK through pip. + +1. **Install the Arcade CLI:** + + ```bash + pip install arcade-ai + ``` + + If you plan on writing evaluations for your tools and the LLMs you use, you will also need to install the `evals` extra. + + ```bash + pip install arcade-ai[evals] + ``` + +2. **Log in to Arcade:** + ```bash + arcade login + ``` + This will prompt you to open a browser and authorize the CLI. It will then save the credentials to your machine typically in `~/.arcade/credentials.json`. + +Now you're ready to build tools with Arcade! + +### Creating a New Tool + +1. **Generate a new toolkit:** + + ```bash + arcade new + ``` + + This will create a new toolkit in the current directory. + + The generated toolkit includes all the scaffolding you need for a working tool. Look for the `mytoolkit/tool.py` file to customize the behavior of your tool. + +2. **Install your new toolkit:** + + ```bash + # make sure you have python and poetry installed + python --version + pip install "poetry<2" + + # install your new toolkit + cd mytoolkit + make install + ``` + +3. **Show the tools in the new Toolkit:** + + ```bash + # show the tools in Mytoolkit + arcade show --local -T Mytoolkit + + # show the definition of a tool + arcade show --local -t Mytoolkit.SayHello + + # show all tools installed in your local python environment + arcade show --local + ``` + +4. **Serve the toolkit:** + + ```bash + # serve the toolkit + arcade serve + ``` + + This will serve the toolkit at `http://localhost:8002`. + +This last command will start a server that hosts your toolkit at `http://localhost:8002`. +If you are running the Arcade Engine locally, go to localhost:9099 (or other local address) +and add the worker address in the "workers" page. + +To use your tools in Arcade Cloud, you can use reverse proxy services like + +- localtunnel (`npm install localtunnel && lt --port 8002`) +- tailscale +- ngrok + +that will provide a tunnel from the local server to Arcade cloud. + +Once hosted on a public address you can head to +https://api.arcade.dev/dashboard/workers and call your toolkits +through the playground, LLM API, or Tools API of Arcade. + +For more details on building your own tools, see the [Tool SDK Documentation](https://docs.arcade.dev/home/build-tools/create-a-tool-with-auth) and see more on calling your own tools below. + +### Sharing Your Toolkit + +To list your toolkit on Arcade, you can open a PR to add your toolkit to the [arcadeai/docs](https://github.com/ArcadeAI/docs) repository. + +

-### Supported Auth Providers +## Calling your tools - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ProviderNameDocumentation
GitHubgithubGitHub Auth Docs
GooglegoogleGoogle Auth Docs
LinkedInlinkedinLinkedIn Auth Docs
MicrosoftmicrosoftMicrosoft Auth Docs
SlackslackSlack Auth Docs
SpotifyspotifySpotify Auth Docs
XxX Auth Docs
ZoomzoomZoom Auth Docs
OAuth 2.0oauth2Generic OAuth2 Auth Docs
+Arcade provides multiple ways to use your tools with various agent frameworks. Depending on your use case, you can choose the best method for your application. -### Supported Language Models +### LLM API -The LLM API supports a variety of language models. Currently, the ones supported in Arcade Cloud are OpenAI, Anthropic, Ollama, and Groq. +The LLM API provides the simplest way to integrate Arcade tools into your application. It extends the standard OpenAI API with additional capabilities: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ModelProviderDocumentation
- OpenAI - OpenAI - OpenAI Models Docs -
- Anthropic - Anthropic - Anthropic Models Docs -
- Ollama - Ollama - Ollama Models Docs -
- Groq - Groq - Groq Models Docs -
+```python +import os +from openai import OpenAI -For more information, refer to the [supported models documentation](https://docs.arcade.dev/home/supported-models). +prompt = "Say hello to Sam" -### Get Started with Arcade +api_key = os.environ["ARCADE_API_KEY"] +openai = OpenAI( + base_url="https://api.arcade.dev/v1", + api_key=api_key, +) -To get started with Arcade, check out our [quickstart guide](https://docs.arcade.dev/home/quickstart). +response = openai.chat.completions.create( + model="gpt-4o-mini", + messages=[ + {"role": "system", "content": "You are a helpful assistant."}, + {"role": "user", "content": prompt}, + ], + tools=["Mytoolkit.SayHello"], + tool_choice="generate", + user="user@example.com" +) -### Building Your Own Tools +print(response.choices[0].message.content) +``` -Learn how to build your own tools by following our [creating a custom toolkit guide](https://docs.arcade.dev/home/build-tools/create-a-toolkit). +When a user hasn't authorized a service, the API seamlessly returns an authorization link in the response: -### Evaluating Tools +``` +Please authorize the tool by visiting: https://some.auth.url.arcade.will.generate.for.you... -Arcade enables you to evaluate your custom tools to ensure they function correctly with the AI assistant, including defining evaluation cases and using different critics. +``` -Learn how to evaluate your tools by following our [evaluating tools guide](https://docs.arcade.dev/home/evaluate-tools/create-an-evaluation-suite). +All you need to do is show the url to the user, and from then on, the user will never have to do this again. All future requests will use the authorized token. -## Contributing +After authorization, the same API call returns the completed action: -We love contributions! Please read our [contributing guide](CONTRIBUTING.md) before submitting a pull request. If you'd like to self-host, refer to the [self-hosting documentation](https://docs.arcade.dev/home/install/overview). +``` +Hello Sam! +``` -

- - ↑ Back to Top ↑ - -

+### Tools API + +Use the Tools API when you want to integrate Arcade's runtime for tool calling into an agent framework (like LangChain or LangGraph), or if you're using your own approach and want to call Arcade tools or tools you've built with the Arcade Tool SDK. + +Here's an example of how to use the Tools API to call a tool directly without a framework: + +```python +import os +from arcadepy import Arcade + +client = Arcade(api_key=os.environ["ARCADE_API_KEY"]) + +# Start the authorization process for Slack +auth_response = client.tools.authorize( + tool_name="Mytoolkit.SayHello", + user_id="user@example.com", +) + +# If the tool is not already authorized, prompt the user to authenticate +if auth_response.status != "completed": + print("Please authorize by visiting:") + print(auth_response.authorization_url) + client.auth.wait_for_completion(auth_response) + +# Execute the tool to send a Slack message after authorization +tool_input = { + "username": "sam", + "message": "I'll be late to the meeting" +} +response = client.tools.execute( + tool_name="Mytoolkit.SayHello", + input=tool_input, + user_id="user@example.com", +) +print(response) + +``` + +### Integrating with Agent Frameworks + +You can also use the Tools API with a framework like LangChain or LangGraph. + +Currently Arcade provides ease-of-use integrations for the following frameworks: + +- LangChain/Langgraph +- CrewAI +- LlamaIndex (coming soon) + +Here's an example of how to use the Tools API with LangChain/Langgraph: + +```python +import os +from langchain_arcade import ArcadeToolManager +from langchain_openai import ChatOpenAI +from langgraph.prebuilt import create_react_agent + +arcade_api_key = os.environ["ARCADE_API_KEY"] +openai_api_key = os.environ["OPENAI_API_KEY"] + +manager = ArcadeToolManager(api_key=arcade_api_key) +tools = manager.get_tools(tools=["Mytoolkit.SayHello"]) + +model = ChatOpenAI( + model="gpt-4o", + api_key=openai_api_key, +) + +bound_model = model.bind_tools(tools) +graph = create_react_agent(model=bound_model, tools=tools) + +config = { + "configurable": { + "thread_id": "1", + "user_id": "user@unique_id.com", + } +} +user_input = { + "messages": [ + { + "role": "system", + "content": "You are a helpful assistant", + }, + { + "role": "user", + "content": "Say hello to Sam", + }, + ] +} + +for chunk in graph.stream(user_input, config, stream_mode="values"): + chunk["messages"][-1].pretty_print() +``` + +### Arcade Auth API + +The Auth API provides the lowest-level integration with Arcade, for when you only need Arcade's authentication capabilities. This API is ideal for: + +- Framework developers building their own agent systems +- Applications with existing tool execution mechanisms +- Developers who need fine-grained control over LLM interactions and tool execution + +With the Auth API, Arcade handles all the complex authentication tasks (OAuth flow management, link creation, token storage, refresh cycles), while you retain complete control over how you interact with LLMs and execute tools. + +```python +from arcadepy import Arcade +from google.oauth2.credentials import Credentials +from googleapiclient.discovery import build + +client = Arcade() + +# Get this user UNIQUE ID from a trusted source, +# like your database or user management system +user_id = "user@example.com" + +# Start the authorization process +response = client.auth.start( + user_id=user_id, + provider="google", + scopes=["https://www.googleapis.com/auth/gmail.readonly"], +) + +if response.status != "completed": + print("Please complete the authorization challenge in your browser:") + print(response.url) + +# Wait for the authorization to complete +auth_response = client.auth.wait_for_completion(response) + +# Use the authorized token in your own tool execution logic +token = auth_response.context.token + +# Example: Using the token with your own Gmail API implementation +credentials = Credentials(token=token) +gmail_service = build('gmail', 'v1', credentials=credentials) +emails = gmail_service.users().messages().list(userId='me').execute() +``` + +## Client Libraries + +- **[ArcadeAI/arcade-py](https://github.com/ArcadeAI/arcade-py):** + The Python client for interacting with Arcade. + +- **[ArcadeAI/arcade-js](https://github.com/ArcadeAI/arcade-js):** + The JavaScript client for interacting with Arcade. + +- **[ArcadeAI/arcade-go](https://github.com/ArcadeAI/arcade-go):** (coming soon) + The Go client for interacting with Arcade. + +## Support and Community + +- **Discord:** Join our [Discord community](https://discord.com/invite/GUZEMpEZ9p) for real-time support and discussions. +- **GitHub:** Contribute or report issues on the [Arcade GitHub repository](https://github.com/ArcadeAI/arcade-ai). +- **Documentation:** Find in-depth guides and API references at [Arcade Documentation](https://docs.arcade.dev).