Introduction

SurfKit is an orchestartor for building and launching agents locally, in a docker container, or in the cloud. Think of it as k8s for agents.

There are several key concepts SurfKit operates with:

• Device is a medium by which an agent interacts with the world. It defines a set of observations and actions available to the agent in solving a task. We currently only support one kind of device which is a Desktop VM, that can run locally (via Docker or QEMU), in GCP or in AWS. We plan to implement more types of devices soon, or you can create one by implementing the DeviceBay protocol.
• Tracker is an entity that takes care of assigning and observing the tasks among the agents. Trackers are run in Docker or in K8s.
• Type is the type of the Agent, for example, SurfPizza, SurfSlicer, or SurfMonsta. The types can be defined either in the Agentsea Hub (more on that later), or in the local repository.
• Agent is an entity of one of the types. That’s the process that is going to solve the tasks for you, that can be executed as a local process (which is super handy during development), in a Docker container or in K8s.
• Task is a unit of an Agent operation that has a description and a device to execute that action against. A task may be as simple as “Find me an image of a cool cat on Google” or as complex as looking for accomodation on Airbnb with lots of filters and search aspects.

The Hub is a place where you can publish and find the agents. It’s in early alpha right now, and we have a lot of deveploment planned for it.

The typical usage of an agent is as follows:

• You pick an agent type from Hub or by cloning a repo.
• You create a device if the agent needs it.
• You create a task tracker (optionally, because it will be created if absent).
• You create an agent of a given type.
• You ask it to solve the task.
• …
• Profit!

If you want to give it a try as quickly as possible, go to Quickstart. On this page, we’ll dive a bit deeper. So let’s go!

If you could only use agents we’ve developed, that wouldn’t be all that useful. SurfKit allows you to create and publish your agents in Hub, so that other people can find and re-use them. See Building Your Agent for details.

​

CLI basics

You can see the detailed (yet incomplete) list of CLI commands at CLI Documentation. To see a complete list of commands do this:

surfkit --help

The goal of this section is to tell you more about the lifecycle of each entity we listed above.

• Devices, Trackers, and Agents are similar: you can create any of them, list them, get information about them (except for trackers), read the logs for agents and trackers and view the devices, and delete any of them to remove the corresponding entity and free up resources.

surfkit create agent
surfkit list agents
surfkit get agent -n foo
surfkit delete agent -n foo

• Tasks are created via solve and you can stop them in UI or by cancelling the process with ctrl+c. You can list them and get information about them while they are in progress.

• Types are the most unique entities in this list:

  • To create a repository for a new type of agent, you run new.
  • Every time you run an agent from the repo, it gets registered in your local database, so you’ll see it via find.
  • To build an image for the agent type, you run build.
  • When the image is uploaded and the agent.yaml is updated, you can login into Hub and publish this type. Now other users will be able to use it!