DOCSEARCHbyAlgolia
Submit Docs

Surfkit Toolkit

repository·main·Indexed 41 days ago

https://github.com/agentsea/surfkit

A toolkit for building, sharing, and running multimodal AI agents that operate on physical or virtual devices. Version 0.1.427 supports local (Docker) and cloud (Kubernetes, GCE) environments. It provides a Python API and CLI for managing agent lifecycles, provisioning devices, tracking tasks via the taskara library, and publishing agents to the AgentSea Hub.

Tokens
13.8K
Snippets
60
Records
70
Agent score
45%

What's inside Surfkit

  1. Quickstart: Solve a task using the CLI

    main

    Use the surfkit solve command to execute a task by specifying an existing agent and device.

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

  2. Quickstart: Solve a task using the Python API

    main

    You can use the solve function from the surfkit module to assign a task to a specific agent type on a specific device type. The function returns a task object that you can wait on to retrieve the result.

    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

  3. Eject from Create React App configuration

    main

    If you need full control over the underlying build tools (webpack, Babel, ESLint, etc.), you can run npm run eject.

    Warning: This is a one-way operation. Once you eject, you cannot go back.

    Running this command copies all configuration files and transitive dependencies directly into your project. While all other commands will still work, they will point to the newly copied scripts, and you will be responsible for maintaining the configuration.

    npm run eject

  4. Manage the surfkit development lifecycle with npm scripts

    main

    The surfkit UI project uses standard npm scripts to manage development, testing, and production builds. Use these commands from the project directory to control the application state.

    # Run the app in development mode
npm start

# Run tests in interactive watch mode
npm test

# Build the app for production
npm run build

# Eject from the build tool configuration (one-way operation)
npm run eject

  6. Track and Solve Tasks

    main

    Manage and monitor agent tasks:

    • surfkit create tracker: Create a new task tracker.
    • surfkit list trackers: List existing trackers.
    • surfkit delete tracker <name>: Delete a tracker.
    • surfkit list tasks: List all tasks.
    • surfkit solve "<task_description>" --agent <agent_name> --device <device_name>: Solve a task using existing infrastructure.
    • surfkit solve "<task_description>" --device <device_name> --agent-file <path_to_yaml>: Solve a task by creating an agent ad hoc from a YAML file.

  8. Build and Run Agents

    main

    For developers building custom agents, use these commands to manage the project lifecycle:

    • surfkit new: Initialize a new project.
    • surfkit build: Build a Docker container for the agent.
    • surfkit create agent --name <name> -t <type>: Create an agent locally.
    • surfkit create agent --runtime kube -t <type>: Create an agent on Kubernetes.

  9. Build surfkit for production

    main
    Execute npm run build to create a production-ready version of the app in the build folder. This process bundles React in production mode and optimizes the build for performance by minifying files and adding content hashes to filenames.
    npm run build

  10. Configure and instantiate agents

    main

    Agents in surfkit are designed to be instantiated via configuration or default settings.

    • from_config(config): Use this to create an agent instance from a specific configuration object. The shape of this object is defined by the class returned by config_type().
    • default(): Use this to create an agent instance with no custom parameters.
    • config_type(): Returns the Type[BaseModel] that defines the schema for the agent's configuration.

  11. Manage agent capabilities with the Skill class

    main

    The Skill class represents a specific capability or toolset an agent possesses. It manages metadata (name, description, requirements), lifecycle status, associated tasks, and configuration via key-value pairs (kvs). Skills can be managed locally in a database or remotely via an API.

    Key attributes include:

    • status: The current lifecycle stage (e.g., TRAINING, DEMO, COMPLETED).
    • requirements: A list of strings defining what the skill must satisfy.
    • tasks: A list of Task objects associated with this skill.
    • kvs: A dictionary for arbitrary configuration data.
    • remote: If set, operations are delegated to a remote API.
    from surfkit.skill import Skill, SkillStatus

# Initialize a new skill
skill = Skill(
    name="search-airbnb",
    description="Search for stays on Airbnb",
    requirements=["find stays within a travel window"],
    status=SkillStatus.CREATED,
    owner_id="user_123"
)

# Save the skill (locally or remotely depending on self.remote)
skill.save()

  12. Use the surfkit CLI to manage agents

    main

    The generated README.md provides the following standard CLI commands for interacting with agents:

    • Create an agent: surfkit create agent -f ./agent.yaml --runtime <process|docker|kube> --name <name>
    • List running agents: surfkit list agents
    • Solve a task: surfkit solve --agent <name> --description "<task_description>" --device-type <device_type>
    • Get agent logs: surfkit logs --name <name>
    • Delete an agent: surfkit delete agent --name <name>
    # Create an agent
surfkit create agent -f ./agent.yaml --runtime docker --name foo

# List running agents
surfkit list agents

# Use the agent to solve a task
surfkit solve --agent foo --description "Search for french ducks" --device-type desktop

# Get the agent logs
surfkit logs --name foo

# Delete the agent
surfkit delete agent --name foo