Superagent

Superagent is an open-source framework for building AI assistants that combines FastAPI, Prefect, and Vercel to enable efficient agent execution through advanced techniques like Server-Sent Events (SSE), concurrency management, and workflow orchestration. This comprehensive guide walks you through the process of creating an AI assistant using Superagent's core technologies, from configuring language models and building agents to deploying your application in various environments. Along the way, you'll learn how to integrate tools, manage workflows, and scale your assistant using Superagent's modular architecture and support for multiple programming languages and external services.

Superagent Framework Overview

Superagent's core technology includes FastAPI for building APIs, Prefect for workflow management, and Vercel for deployment. The framework's architecture enables efficient agent execution through advanced techniques like Server-Sent Events (SSE), concurrency, and workflow orchestration.

Agents in Superagent represent programs with access to datasources and tools, forming the foundation of the AI assistant system. Each agent maintains short-term memory for retaining information from interactions, crucial for maintaining context during conversations. The framework supports multiple programming languages via client libraries for Python, Node/TypeScript, and Swift, allowing developers to build agents using their preferred language environment.

Building an AI assistant with Superagent requires configuring language models, creating agents, and attaching tools. The development process can be conducted locally using Docker, Render, Replit, or other supported environments. Basic setup involves creating a language model instance and an agent configuration, then linking the model to the agent. Each agent can perform specific tasks based on its configuration and the attached tools, which can include browser functionality or third-party API integrations.

The deployment process for Superagent applications depends on the chosen development environment. For local development, users must set up Supabase UI with authentication through passwordless methods or GitHub OAuth, managing environment variables for database connections and API keys. The application architecture supports multiple vector databases and external tools, providing flexibility for different use cases while maintaining consistent core functionality.

Superagent Cloud Platform

Superagent's cloud platform utilizes FastAPI for building robust APIs, Prefect for sophisticated workflow management, and Vercel for deployment of the Superagent User Interface (UI). This infrastructure enables efficient agent execution through advanced techniques including Server-Sent Events (SSE), concurrency management, and workflow orchestration.

The platform's technical foundation comprises FastAPI as the primary web framework, Prefect for reliable task orchestration, and Vercel for seamless deployment. By leveraging these technologies, Superagent creates a scalable and maintainable environment for AI assistant development and deployment.

Agent development in Superagent centers around creating programs with access to datasources and tools. Each agent maintains internal memory for managing conversation context, storing information from previous interactions to inform current responses. The system supports multiple programming languages via client libraries for Python, Node/TypeScript, and Swift, offering flexibility for developers working in various environments.

Building an AI assistant with Superagent requires interacting with its REST API to configure language models, create agents, and attach tools. Basic setup involves creating a language model instance and an agent configuration, then linking the model to the agent through the API. The framework enables sophisticated workflows by allowing multiple agents to process information in sequence, with output from one agent serving as input for the next.

The development process supports multiple deployment methods, including Docker, Render, Replit, or direct local execution. For local development, users must set up Supabase UI with either passwordless authentication or GitHub OAuth. Environment variables manage connections to vector databases and external tools, providing the necessary infrastructure for running Superagent applications.

Agent and Tooling System

Agent development in Superagent centers around creating programs with access to datasources and tools. Each agent maintains internal memory for managing conversation context, storing information from previous interactions to inform current responses. This short-term memory capability enables the agent to maintain context and provide relevant responses or actions based on the information it has processed.

The Superagent platform supports multiple programming languages via client libraries for Python, Node/TypeScript, and Swift, offering flexibility for developers working in various environments. The development process involves creating language model instances and agent configurations, then linking models to agents through the Superagent API. Agents can perform specific tasks based on their configuration and attached tools, with the system supporting complex workflows that can break down large tasks into manageable parts.

Attached tools enable specific functionalities like internet browsing or code execution within the agent environment. These tools are created using the Superagent client library and can include functionality for browsing the web, executing code, or accessing third-party APIs. The system allows for structured outputs and supports multiple data types including structured CSV and JSON files, as well as unstructured PDF and text documents.

The platform's workflow structure allows for sequences of agents running in specific orders, with output from one agent passed to the next in the sequence. This modular approach enables the creation of sophisticated systems for various tasks, while the underlying architecture supports multiple vector databases and external tools through interfaces like Pinecone and Weaviate.

The Superagent framework constantly evolves based on community feedback, incorporating core principles of active learning, flexibility, and collaboration between humans and AI agents. This development approach aims to create more autonomous and adaptable AI systems that can scale with foundation model improvements while maintaining meaningful human collaboration.

Development and API Usage

Building an AI assistant with Superagent begins with configuring essential components through the framework's REST API. The setup process involves creating a language model instance and an agent configuration, then linking these elements together. Here's a detailed breakdown of the development workflow:

Client SDK Installation

Superagent supports multiple programming languages via client libraries:

• Python: superagent-py

• Node/TypeScript: superagent-js (maintained by the community)

• Swift: Maintained by the community

Basic Assistant Setup

The development process starts with setting up environment variables for API keys and URLs. For example, in Python, you'll need:

import os

from superagent.client import Superagent

client = Superagent(

<pre><code>base_url="https://api.beta.superagent.sh",

token=os.environ["SUPERAGENT_API_KEY"]
</code></pre>

)

Language Model Configuration

The framework requires a language model provider, typically OpenAI. Here's how to configure it:

llm = client.llm.create(request={

<pre><code>"provider": "OPENAI",

"apiKey": os.environ["OPENAI_API_KEY"]
</code></pre>

})

Agent Creation

An assistant is created with specific attributes:

agent = client.agent.create(

<pre><code>name="Chat Assistant",

description="My first Assistant",

type="SUPERAGENT",

avatar="https://myavatar.com/homanp.png",

is_active=True,

initial_message="Hi there! How can I help you?",

llm_model="GPT_3_5_TURBO_16K_0613",

prompt="You are a helpful AI Assistant"
</code></pre>

)

Tool Integration

Superagent supports various tools, including a browser tool:

client.agent.add_tool(agent_id=agent.data.id, tool_type="BROWSER", tool_metadata={"return_direct": True})

Agent Invocation

To process user input, you'll use the constructed agent:

client.agent.invoke(agent_id=agent.data.id, input_text="What's the weather like today?", stream=False, session_id="my_session")

Running Locally

For local development, follow these steps:

1. Clone the repository and navigate to /libs/ui

2. Install Supabase CLI and create a project

3. Start the local Supabase project

4. Run database migrations

5. Set authentication with passwordless methods or GitHub OAuth

The application can be accessed at http://localhost:3000. The environment requires specific variables including API keys and URLs. This local development environment mirrors the production deployment setup provided by Vercel, ensuring consistent development and staging experiences.

Deployment and Architecture

To deploy a Superagent application, the development team must set up Supabase UI and handle authentication through passwordless methods or GitHub OAuth. Development occurs in a structured environment that supports multiple vector databases and external tools, with the architecture designed for efficient agent execution through advanced techniques including Server-Sent Events (SSE), concurrency, and workflow orchestration.

Local Development Setup

Local development requires cloning the repository and navigating to the /libs/ui directory. The process includes creating an environment file by copying .env.example, setting mandatory environment variables, creating a virtual environment, installing dependencies with poetry, starting Supabase with supabase start, and generating the Prisma schema. The server runs on http://127.0.0.1:8000, accessible at http://127.0.0.1:8000/api/v1.

Supabase Configuration

The Supabase project requires specific setup including authentication setup through passwordless methods or GitHub OAuth. Development involves creating a new GitHub OAuth app, copying the CLIENT_ID and CLIENT_SECRET, and configuring the callback URL. The frontend and backend environments require several environment variables including Supabase URL, anonymous key, storage name, segment write key, and API endpoints for various services.

Deployment Requirements

For deployment, the application needs detailed configuration including database details, JWT secret, vector store configuration, and API keys for various services. The setup requires specific environment variables for operation, including details for OpenAI API, database connection, and third-party service integrations. The framework supports multiple architectures through its flexible deployment options, including Docker, Render, and Replit, while the underlying infrastructure leverages FastAPI, Prefect, and Vercel for efficient execution and management.