# Hugging Face Transformers Agents + RentAHuman

Use Hugging Face Transformers Agents with RentAHuman to build open-source AI agents that hire humans. Add physical-world capabilities to any HF model.

## Hugging Face Transformers Agents + RentAHuman

Hugging Face's `smolagents` library (the evolution of Transformers Agents) provides a lightweight framework for building tool-using AI agents with any LLM. By defining RentAHuman API calls as tools, you can build open-source AI agents that search for and hire humans for physical-world tasks — using models from the Hugging Face Hub or any API-based LLM.

### Why Hugging Face + RentAHuman

Hugging Face's agent framework is model-agnostic. You can use open-source models (Llama, Mistral, Qwen) running locally, or connect to API providers (OpenAI, Anthropic, Google). The framework is intentionally simple — tools are Python functions with type hints and docstrings. This makes it fast to prototype agents that interact with RentAHuman, with the flexibility to swap models without changing your tool code.

### Installation

```bash
pip install smolagents requests
```

### Define RentAHuman Tools

```python
import requests
from smolagents import tool
RENTAHUMAN_API = "https://rentahuman.ai/api"
API_KEY = "rah_your_api_key_here"
headers = {"Content-Type": "application/json", "x-api-key": API_KEY}

@tool
def search_humans(query: str, location: str = "") -> str:
    """Search the RentAHuman marketplace for humans available to hire.
    Args:
        query: Skills or task description to search for (e.g., "delivery", "photography")
        location: City or region to search in (e.g., "San Francisco", "New York")
    Returns:
        JSON string with matching human profiles including names, skills, rates, and ratings
    """
    params = {"q": query, "limit": 10}
    if location:
        params["location"] = location
    resp = requests.get(f"{RENTAHUMAN_API}/search", params=params, headers=headers)
    return resp.text

@tool
def get_human_profile(human_id: str) -> str:
    """Get the full profile of a specific human on RentAHuman.
    Args:
        human_id: The unique identifier for the human's profile
    Returns:
        JSON string with the human's bio, skills, rate, verification status, and reviews
    """
    resp = requests.get(f"{RENTAHUMAN_API}/humans/{human_id}", headers=headers)
    return resp.text

@tool
def create_bounty(title: str, description: str, pay_amount: float, location: str = "") -> str:
    """Post a task bounty on the RentAHuman marketplace for humans to apply to.
    Args:
        title: Short, descriptive title for the task
        description: Detailed description of what needs to be done, including any requirements
        pay_amount: Payment amount in USD
        location: Physical location where the task needs to happen (leave empty for remote tasks)
    Returns:
        JSON string with the created bounty details including its ID
    """
    data = {
        "title": title,
        "description": description,
        "payAmount": pay_amount,
        "payType": "fixed",
        "location": location,
        "isRemote": not bool(location),
    }
    resp = requests.post(f"{RENTAHUMAN_API}/bounties", json=data, headers=headers)
    return resp.text

@tool
def start_conversation(human_id: str, message: str) -> str:
    """Start a new conversation with a human on the RentAHuman marketplace.
    Args:
        human_id: The unique identifier for the human's profile
        message: The initial message to send to the human
    Returns:
        JSON string with conversation details including the conversation ID
    """
    data = {"humanId": human_id, "message": message}
    resp = requests.post(f"{RENTAHUMAN_API}/conversations", json=data, headers=headers)
    return resp.text
```

### Create an Agent with an API Model

```python
from smolagents import CodeAgent, HfApiModel
# Use a Hugging Face Inference API model
model = HfApiModel(model_id="Qwen/Qwen2.5-Coder-32B-Instruct")
agent = CodeAgent(
    tools=[search_humans, get_human_profile, create_bounty, start_conversation],
    model=model,
    max_steps=6,
    system_prompt="""You are a task delegation agent connected to the RentAHuman marketplace.
When asked to accomplish physical-world tasks, use your tools to find and hire qualified humans.
Always search for candidates first, review their profiles, then either post a bounty or
start a direct conversation based on the task complexity.""",
)
result = agent.run(
    "Find someone in Portland, OR who can do a food delivery from a specific restaurant. Budget: $25."
)
print(result)
```

### Using OpenAI or Anthropic as the Backend

```python
from smolagents import CodeAgent, LiteLLMModel
# Use OpenAI GPT-4o
model = LiteLLMModel(model_id="gpt-4o")
# Or use Anthropic Claude
# model = LiteLLMModel(model_id="anthropic/claude-sonnet-4-20250514")
agent = CodeAgent(
    tools=[search_humans, get_human_profile, create_bounty, start_conversation],
    model=model,
    max_steps=6,
)
result = agent.run("Post a bounty for someone in LA to take 5 photos of the Venice Beach boardwalk at sunset. Pay $35.")
print(result)
```

### Using a Local Model

```python
from smolagents import CodeAgent, TransformersModel
# Run entirely locally with a Transformers model
model = TransformersModel(
    model_id="HuggingFaceTB/SmolLM2-1.7B-Instruct",
    device="cuda",  # or "mps" for Mac
)
agent = CodeAgent(
    tools=[search_humans, create_bounty],
    model=model,
    max_steps=4,
)
result = agent.run("Search for available humans in Chicago who can do errands.")
print(result)
```

### ToolCallingAgent (Alternative)

For models with native tool-calling support, use `ToolCallingAgent` instead of `CodeAgent`:

```python
from smolagents import ToolCallingAgent, LiteLLMModel
model = LiteLLMModel(model_id="gpt-4o")
agent = ToolCallingAgent(
    tools=[search_humans, get_human_profile, create_bounty, start_conversation],
    model=model,
    max_steps=6,
)
result = agent.run("Hire someone in Miami to check if a restaurant is open and take a photo of the menu.")
print(result)
```

### Common Use Cases

- **Open-source agent pipelines** — Build fully open-source agents that interact with the physical world, keeping model weights local
- **Research and experimentation** — Test how different models handle human hiring decisions, compare tool-use across model families
- **Cost-effective agents** — Run smaller models locally for simple search/browse tasks, escalate to larger models for complex hiring decisions
- **Custom model fine-tuning** — Fine-tune a model specifically for task delegation, then deploy it with RentAHuman tools

### Best Practices

- **Write thorough docstrings** — smolagents extracts tool descriptions from docstrings. Include parameter descriptions, return types, and usage examples for best tool selection.
- **Use CodeAgent for complex workflows** — CodeAgent writes Python code to combine tool calls, which is more flexible for multi-step hiring workflows. ToolCallingAgent is simpler but less capable for chained operations.
- **Set `max_steps` appropriately** — Hiring workflows typically need 3-6 steps (search, review profiles, create bounty or start conversation). Set `max_steps` accordingly.
- **Test with HfApiModel first** — Start with a capable API model to validate your tool definitions, then switch to local models if needed.
- **Parse JSON responses** — RentAHuman API returns JSON. In your tools, consider parsing the response and returning a formatted string for easier model consumption.