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.

Agent Source Types

Runloop supports four types of agent sources:

Source Type	Description	Use Case
Git	Clone an agent from a Git repository	Custom agents, open source agents
npm	Install an agent from npm registry	Node.js-based agents
pip	Install an agent from PyPI	Python-based agents
Object	Use an agent from a Runloop Object	Pre-packaged agent bundles, custom builds. A Git repository can also be uploaded as an object and will initialize faster than cloning.

Which Agent Source Type to Choose?

Choose the integration pattern that best matches how the agent is developed, versioned, and deployed. The best choice depends on how often the agent changes, how it’s distributed, and how much flexibility you need at runtime.Package-based agents (pip / npm) are the simplest option when the agent is already published to a public or private package registry and follows conventional release practices. This works well for agents with stable, versioned releases and minimal build requirements. Package installation integrates cleanly with existing dependency management workflows and makes it easy to pin or upgrade agent versions over time.Git-based agents are an excellent alternative if you own the agent’s source code, or need tighter control over how it’s built and executed. Installing from Git allows you to run directly from source, target a specific branch or commit hash, and customize build or runtime behavior. This is especially useful during active development or when integrating internal agents that aren’t published to a package registry.Object-based agents are ideal for prebuilt or precompiled agents, or for agents that don’t naturally fit into a Python or Node.js packaging model. By packaging the agent ahead of time and storing it as a Runloop Object, you can significantly reduce startup time and avoid repeated build steps. This approach is well suited for agents written in other languages, agents with complex build pipelines, or production workloads where fast, deterministic startup is important.

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
API Reference: Create an Agent - Full API documentation
API Reference: Get an Agent - Retrieve agent details
API Reference: List Agents - List your agents

Overview

Tools

Components

Repo Connect

Benchmarks & Evals

Debugging

Developer Tools

Overview

Agent Source Types

Which Agent Source Type to Choose?

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

Repo Connect

Benchmarks & Evals

Debugging

Developer Tools

​Overview

​Agent Source Types

​Which Agent Source Type to Choose?

​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

Agent Source Types

Which Agent Source Type to Choose?

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