Surfkit

A toolkit for building and sharing AI agents that operate on devices
Explore the docs »

View Demo · Report Bug · Request Feature

Features

• Build multimodal agents that can operate on devices
• Share agents with the community
• Run agents and devices locally or in the cloud
• Manage agent tasks at scale
• Track and observe agent actions

Demo

agentsea_demo.mp4

Installation

pip install surfkit

Quickstart

Prerequisites

• Docker
• Python >= 3.10
• MacOS or Linux

Python

Use an agent to solve a task

from surfkit import solve

task = solve(
    "Search for the most common variety of french duck",
    agent_type="pbarker/SurfPizza",
    device_type="desktop",
  )

task.wait_for_done()

result = task.result

CLI

Create an Agent

Find available agents on the Hub

surfkit find

Create a new agent

surfkit create agent -t pbarker/SurfPizza -n agent01

List running agents

surfkit list agents

Create a Device

Create an Ubuntu desktop for our agent to use.

surfkit create device --provider docker -n desktop01

List running devices

surfkit list devices

Solve a task

Use the agent to solve a task on the device

surfkit solve "Search for the most common variety of french duck" \
  --agent agent01 \
  --device desktop01

Documentation

View our documentation for more in depth information.

Usage

Building Agents

Initialize a new project

surfkit new

Build a docker container for the agent

surfkit build

Running Agents

Create an agent locally

surfkit create agent --name foo -t pbarker/SurfPizza

Create an agent on kubernetes

surfkit create agent --runtime kube -t pbarker/SurfPizza

List running agents

surfkit list agents

Get details about a specific agent

surfkit get agent foo

Fetch logs for a specific agent

surfkit logs foo

Delete an agent

surfkit delete agent foo

Managing Devices

Create a device

surfkit create device --type desktop --provicer gce --name bar

List devices

surfkit list devices

View device in UI

surfkit view bar

Delete a device

surfkit delete device bar

Tracking Tasks

Create a tracker

surfkit create tracker

List trackers

surfkit list trackers

Delete a tracker

surfkit delete tracker foo

Solving Tasks

Solve a task with an existing setup

surfkit solve "search for common french ducks" --agent foo --device bar

Solve a task creating the agent ad hoc

surfkit solve "search for alpaca sweaters" \
--device bar --agent-file ./agent.yaml

List tasks

surfkit list tasks

Publishing Agents

Login to the hub

surfkit login

Publish the agent

surfkit publish

List published agent types

surfkit find

Integrations

Skillpacks is integrated with:

• MLLM A prompt management, routing, and schema validation library for multimodal LLMs
• Taskara A task management library for AI agents
• Skillpacks A library to fine tune AI agents on tasks.
• Threadmem A thread management library for AI agents

Community

Come join us on Discord.

Developing

Add the following function to your ~/.zshrc (or similar)

function sk() {
  local project_dir="/path/to/surfkit/repo"
  local venv_dir="$project_dir/.venv"
  local ssh_auth_sock="$SSH_AUTH_SOCK"
  local ssh_agent_pid="$SSH_AGENT_PID"

  export SSH_AUTH_SOCK="$ssh_auth_sock"
  export SSH_AGENT_PID="$ssh_agent_pid"

  # Add the Poetry environment's bin directory to the PATH
  export PATH="$venv_dir/bin:$PATH"

  # Execute the surfkit.cli.main module using python -m
  surfkit "$@"
}

Replacing /path/to/surfkit/repo with the absolute path to your local repo.

Then calling sk will execute the working code in your repo from any location.