Using the Agents API

Start with the Runloop Quickstart to use the examples below.

Overview

The Agents API allows you to create, manage, and deploy AI agents on the Runloop platform. Agents can be sourced from Git repositories, npm packages, PyPI packages, or Runloop Objects. Once created, agents can be mounted to Devboxes and used in your workflows.

Why Use Agent Objects?

Registering an agent with the Agents API gives you control over how agents are installed, versioned, and distributed. There are three common motivations: Fast, reliable installs. Every time a devbox starts, the agent needs to be ready. Downloading dependencies from external servers on every launch introduces latency and risk — package registries can be slow, rate-limited, or temporarily unavailable. Object-based agents solve this by bundling everything into a pre-packaged archive stored on Runloop, eliminating wide-area network traffic entirely. Git and package-based agents still fetch from upstream servers, but registering them as Runloop agents caches metadata and streamlines the install process. Explicit version control. You want to know exactly which version of an agent is running. Each source type supports this differently:

Git agents can pin to a specific branch, tag, or commit SHA via the ref field
npm/pip agents use standard lock files (package-lock.json, requirements.txt with pinned versions) to freeze the dependency tree
Object-based agents are inherently immutable — the archive you upload is exactly what gets installed

Publishing and distribution. You may want to publish an agent from your source repository for internal or external use, with regular releases. The Agents API provides a central registry where you can create versioned agent entries, making it easy to reference them by name or ID when creating devboxes. Combined with the deploy-agent GitHub Action, you can automate publishing new agent versions on every release.

Agent Source Types

Runloop supports four types of agent sources. Choose the one that best matches how your agent is developed, versioned, and deployed.

Source Type	Description	Best For
Git	Clone from a Git repository	Agents in active development, or when you need to target a specific branch or commit
npm	Install from npm registry	Node.js agents with stable, versioned releases on npm
pip	Install from PyPI	Python agents with stable, versioned releases on PyPI
Object	Unpack from a Runloop storage object	Pre-packaged bundles, compiled agents, or production workloads needing fast deterministic startup

Package-based agents (pip / npm) are the simplest option when the agent is already published to a registry and follows conventional release practices. Package installation integrates cleanly with existing dependency management workflows.Git-based agents give you tighter control — run directly from source, target a specific commit, and customize build or runtime behavior. Especially useful during active development or for internal agents that aren’t published to a registry.Object-based agents eliminate external dependencies at startup. By packaging the agent ahead of time and storing it as a Runloop Object, you avoid repeated downloads and build steps. Well suited for agents with complex build pipelines, agents written in compiled languages, or any workload where fast startup matters.

Creating Agents

Creating an Agent from a Git Repository

Create an agent by cloning a Git repository. This is ideal for custom agents or open source agents hosted on GitHub, GitLab, or other Git providers.

import asyncio
from runloop_api_client import AsyncRunloopSDK

runloop = AsyncRunloopSDK()

agent = await runloop.agent.create(
  name="my-git-agent",
  version="1.0.0",
  source={
    "type": "git",
    "git": {
      "repository": "https://github.com/username/my-agent-repo",
      "ref": "main"  # Optional: branch, tag, or commit SHA
    }
  }
)

print(f"Created agent: {agent.id}")
print(f"Agent name: {agent.name}")
print(f"Agent version: {agent.version}")

Creating an Agent from an npm Package

Create an agent from an npm package. The package will be installed globally when the devbox is created.

agent = await runloop.agent.create(
  name="my-npm-agent",
  version="2.0.0",
  source={
    "type": "npm",
    "npm": {
      "package_name": "@anthropic-ai/claude-code",
      "registry_url": None  # Optional: custom registry URL
    }
  }
)

print(f"Created agent: {agent.id}")

Creating an Agent from a PyPI Package

Create an agent from a PyPI package. The package will be installed globally when the devbox is created.

agent = await runloop.agent.create(
  name="my-pip-agent",
  version="1.5.0",
  source={
    "type": "pip",
    "pip": {
      "package_name": "my-agent-package",
      "registry_url": None  # Optional: custom registry URL
    }
  }
)

print(f"Created agent: {agent.id}")

Creating an Agent from a Storage Object

Create an agent from a Runloop Object. This is useful for pre-packaged agent bundles, custom builds, or agents that require specific file structures.

Before creating an object-based agent, you need to upload your agent files as a Runloop Object. See the Runloop Objects documentation for details on creating objects.

Step 1: Upload Agent Files as a Runloop Object

First, package your agent files and upload them as an object. You can upload a tar archive (.tar, .tar.gz, .tgz) or a single file.

# Option 1: Upload a tar archive containing your agent files
runloop_object = await runloop.storage_object.upload_from_file(
  file_path='./my-agent.tar.gz',
  name='my-agent-bundle.tar.gz'
)

# Option 2: Upload a single file
runloop_object = await runloop.storage_object.upload_from_text(
  text='#!/usr/bin/env python3\nprint("Hello from agent")',
  name='agent.py'
)

object_id = runloop_object.id
print(f"Uploaded object: {object_id}")

Step 2: Create Agent from Runloop Object

Once you have the object ID, create an agent using the object source. You can optionally provide setup commands to run after unpacking the object.

agent = await runloop.agent.create(
  name="my-object-agent",
  version="1.0.0",
  source={
    "type": "object",
    "object": {
      "object_id": object_id,
      "agent_setup": [
        "chmod +x agent.py",
        "pip install -r requirements.txt"
      ]
    }
  }
)

print(f"Created agent: {agent.id}")

Complete Example: Creating an Object-Based Agent

Here’s a complete example that packages agent files, uploads them, and creates an agent:

import asyncio
import tarfile
from runloop_api_client import AsyncRunloopSDK

runloop = AsyncRunloopSDK()

async def create_object_agent():
  # Step 1: Package agent files into a tar archive
  with tarfile.open('agent-bundle.tar.gz', 'w:gz') as tar:
    tar.add('agent.py', arcname='agent.py')
    tar.add('requirements.txt', arcname='requirements.txt')
    tar.add('config.json', arcname='config.json')
  
  # Step 2: Upload the archive as a storage object
  storage_object = await runloop.storage_object.upload_from_file(
    file_path='./agent-bundle.tar.gz',
    name='agent-bundle.tar.gz'
  )
  
  # Step 3: Create agent from the storage object
  agent = await runloop.agent.create(
    name="my-packaged-agent",
    version="1.0.0",
    source={
      "type": "object",
      "object": {
        "object_id": storage_object.id,
        "agent_setup": [
          "pip install -r requirements.txt",
          "chmod +x agent.py"
        ]
      }
    }
  )
  
  print(f"Created agent: {agent.id}")
  print(f"Agent name: {agent.name}")
  return agent

asyncio.run(create_object_agent())

Retrieving Agents

Get a Specific Agent

Retrieve details about a specific agent by its ID.

agent = await runloop.agent.from_id('agt_abc123xyz')
agent_details = await agent.get_info()

print(f"Agent ID: {agent_details.id}")
print(f"Agent name: {agent_details.name}")
print(f"Agent version: {agent_details.version}")
print(f"Source type: {agent_details.source.type if agent_details.source else 'None'}")

Listing Agents

List Your Agents

Retrieve a list of all agents in your account.

agents_list = await runloop.agent.list(limit=20)

print(f"Total agents: {agents_list.total_count}")

for agent in agents_list.agents:
  print(f"- {agent.name} (ID: {agent.id}, Version: {agent.version})")

Agent Versioning

Agents use semantic versioning (semver) or Git SHAs for versioning. When creating an agent, specify a version string:

Semver format: "1.0.0", "2.1.5", "0.1.0-alpha"
Git SHA: "abc123def456..." (full or partial commit SHA)

# Using semver
agent_v1 = await runloop.agent.create(
  name="my-agent",
  version="1.0.0",
  source={"type": "git", "git": {"repository": "https://github.com/user/repo"}}
)

# Using Git SHA
agent_sha = await runloop.agent.create(
  name="my-agent",
  version="abc123def456",
  source={"type": "git", "git": {"repository": "https://github.com/user/repo", "ref": "abc123def456"}}
)

Using Agents with Devboxes

Once you’ve created an agent, you can mount it onto a Devbox. See the Agent Mounts documentation for details on using agents with Devboxes.

# Create a devbox with an agent mount
devbox = await runloop.devbox.create(
  mounts=[
    {
      "type": "agent_mount",
      "agent_name": "my-agent",
      # "agent_id": "agt_abc123xyz",
      # Use one of agent_name or agent_id. When using agent_name the most recently created agent with a matching name will be used.
      "agent_path": "/home/user/agent"
    }
  ]
)

Best Practices

Agent Naming

Use descriptive names: Choose clear, meaningful names for your agents
- ✅ code-review-agent
- ❌ agent1
Use consistent versioning: Follow semantic versioning for predictable releases
- ✅ 1.0.0, 1.1.0, 2.0.0
- ❌ v1, latest, new

Source Type Selection

Git: Best for version-controlled agents, custom development, open source agents
npm: Best for Node.js-based agents available on npm
pip: Best for Python-based agents available on PyPI
Object: Best for pre-packaged agents, custom builds, or agents with complex dependencies

Object-Based Agents

Include setup commands: Use agent_setup to automate installation and configuration
Check compatibility: Object-based agents are particularly useful when developing agents in compiled languages. Make sure that any compiled binaries work on all target platforms.

Security

Private repositories: Use authentication tokens for private Git repositories
Sensitive data: Avoid storing secrets or API keys in agent packages and within Runloop Objects

Agent Mounts - Mount agents to Devboxes
Objects - Upload and manage storage objects

Overview

Tools

Components

Benchmarks & Evals

Debugging

Overview

Why Use Agent Objects?

Agent Source Types

Creating Agents

Creating an Agent from a Git Repository

Creating an Agent from an npm Package

Creating an Agent from a PyPI Package

Creating an Agent from a Storage Object

Step 1: Upload Agent Files as a Runloop Object

Step 2: Create Agent from Runloop Object

Complete Example: Creating an Object-Based Agent

Retrieving Agents

Get a Specific Agent

Listing Agents

List Your Agents

Agent Versioning

Using Agents with Devboxes

Best Practices

Agent Naming

Source Type Selection

Object-Based Agents

Security

Overview

Tools

Components

Benchmarks & Evals

Debugging

​Overview

​Why Use Agent Objects?

​Agent Source Types

​Creating Agents

​Creating an Agent from a Git Repository

​Creating an Agent from an npm Package

​Creating an Agent from a PyPI Package

​Creating an Agent from a Storage Object

​Step 1: Upload Agent Files as a Runloop Object

​Step 2: Create Agent from Runloop Object

​Complete Example: Creating an Object-Based Agent

​Retrieving Agents

​Get a Specific Agent

​Listing Agents

​List Your Agents

​Agent Versioning

​Using Agents with Devboxes

​Best Practices

​Agent Naming

​Source Type Selection

​Object-Based Agents

​Security

​Related Documentation

Overview

Why Use Agent Objects?

Agent Source Types

Creating Agents

Creating an Agent from a Git Repository

Creating an Agent from an npm Package

Creating an Agent from a PyPI Package

Creating an Agent from a Storage Object

Step 1: Upload Agent Files as a Runloop Object

Step 2: Create Agent from Runloop Object

Complete Example: Creating an Object-Based Agent

Retrieving Agents

Get a Specific Agent

Listing Agents

List Your Agents

Agent Versioning

Using Agents with Devboxes

Best Practices

Agent Naming

Source Type Selection

Object-Based Agents

Security

Related Documentation