Initial fast-agent deployment with Python 3.13 and uv

.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.env
+*.log
+fastagent.jsonl

DEPLOYMENT.md

@@ -0,0 +1,187 @@
+# Deploying Fast-Agent to Hugging Face Spaces
+
+## Quick Start
+
+This directory contains everything you need to deploy fast-agent to a Hugging Face Space.
+
+## Files Overview
+
+- **README.md**: Space metadata and description (with YAML header)
+- **Dockerfile**: Docker image definition (Python 3.13 + uv)
+- **agent.md**: Agent card defining the agent's capabilities and tools
+- **hf_api_tool.py**: Python tool for HF API access (from fast-agent examples)
+- **.gitignore**: Files to ignore in git
+
+## Deployment Steps
+
+### 1. Create a New Space
+
+Go to https://huggingface.co/new-space and:
+- Choose a name for your Space
+- Select **Docker** as the SDK
+- Choose visibility (Public or Private)
+- Click "Create Space"
+
+### 2. Clone Your Space Repository
+
+```bash
+git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+cd YOUR_SPACE_NAME
+```
+
+### 3. Copy Files
+
+Copy all files from this directory to your Space repository:
+
+```bash
+cp /path/to/this/directory/* YOUR_SPACE_NAME/
+```
+
+Or manually copy:
+- README.md
+- Dockerfile
+- agent.md
+- hf_api_tool.py
+- .gitignore
+
+### 4. Commit and Push
+
+```bash
+git add .
+git commit -m "Initial fast-agent deployment"
+git push
+```
+
+### 5. Wait for Build
+
+Hugging Face will automatically:
+- Build the Docker image (Python 3.13 + uv)
+- Deploy the container
+- Make it available at your Space URL
+
+This usually takes 2-5 minutes.
+
+### 6. (Optional) Add Secrets
+
+If your agent needs authentication:
+
+1. Go to your Space settings
+2. Navigate to "Repository secrets"
+3. Add `HF_TOKEN` with your Hugging Face token
+4. Restart the Space
+
+## Testing Locally
+
+Before deploying, you can test locally:
+
+```bash
+# Build the Docker image
+docker build -t fast-agent-space .
+
+# Run it locally
+docker run -p 7860:7860 -e HF_TOKEN=your_token fast-agent-space
+
+# Test the endpoint
+curl http://localhost:7860
+```
+
+## Technical Details
+
+### Python & Dependencies
+
+- **Python 3.13**: Using the latest slim image
+- **uv**: Astral's fast Python package installer
+- **System packages**: bash, git, git-lfs, wget, curl, procps
+
+The Dockerfile uses `uv pip install --system` for faster, more reliable package installation.
+
+## Customization
+
+### Change the Agent Card
+
+Edit `agent.md` to modify:
+- Agent name
+- Model (e.g., `gpt-4`, `claude-3-sonnet`, etc.)
+- Instructions
+- Tool references
+
+### Add More Tools
+
+1. Create a new Python file (e.g., `my_tool.py`)
+2. Add your tool function
+3. Reference it in `agent.md`:
+   ```yaml
+   function_tools:
+     - hf_api_tool.py:hf_api_request
+     - my_tool.py:my_function
+   ```
+
+### Multiple Agent Cards
+
+Modify the Dockerfile CMD to include multiple cards:
+
+```dockerfile
+CMD ["fast-agent", "serve", "--card", "agent1.md", "--card", "agent2.md", "--port", "7860"]
+```
+
+### Change the Model
+
+Add `--model` to the CMD in Dockerfile:
+
+```dockerfile
+CMD ["fast-agent", "serve", "--card", "agent.md", "--model", "gpt-4", "--port", "7860"]
+```
+
+### Additional Dependencies
+
+If you need extra Python packages, add them after the fast-agent-mcp install:
+
+```dockerfile
+RUN uv pip install --system --no-cache fast-agent-mcp my-package another-package
+```
+
+Or use a requirements.txt:
+
+```dockerfile
+COPY requirements.txt .
+RUN uv pip install --system --no-cache -r requirements.txt
+```
+
+## Accessing Your Agent
+
+Once deployed, your agent will be accessible as an HTTP API at:
+```
+https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space
+```
+
+You can interact with it via HTTP requests or use it as an MCP server.
+
+## Troubleshooting
+
+### Space Won't Build
+
+Check the build logs in your Space for errors. Common issues:
+- Missing dependencies in Dockerfile
+- Syntax errors in agent.md
+- Tool file not found
+
+### Space Runs But Errors
+
+Check the application logs. Common issues:
+- Model API key not configured
+- Port mismatch (must be 7860)
+- Tool import errors
+
+### Need More Resources
+
+If you need more CPU/RAM:
+1. Go to Space settings
+2. Upgrade to a paid tier
+3. Select appropriate hardware
+
+## Support
+
+- Fast-Agent GitHub: https://github.com/evalstate/fast-agent
+- Fast-Agent PyPI: https://pypi.org/project/fast-agent-mcp/
+- Hugging Face Spaces docs: https://huggingface.co/docs/hub/spaces
+- Astral uv docs: https://docs.astral.sh/uv/

Dockerfile

@@ -0,0 +1,34 @@
+FROM python:3.13-slim
+
+# Install system dependencies required by fast-agent and HF Spaces
+RUN apt-get update && \
+    apt-get install -y \
+      bash \
+      git git-lfs \
+      wget curl procps \
+      && rm -rf /var/lib/apt/lists/*
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# Set working directory
+WORKDIR /app
+
+# Install fast-agent-mcp using uv
+RUN uv pip install --system --no-cache fast-agent-mcp
+
+# Copy all files from the Space repository to /app
+COPY --link ./ /app
+
+# Ensure /app is owned by uid 1000 (required for HF Spaces)
+RUN chown -R 1000:1000 /app
+
+# Switch to non-root user
+USER 1000
+
+# Expose port 7860 (HF Spaces default)
+EXPOSE 7860
+
+# Run fast-agent serve
+# The agent card (agent.md) and tool file (hf_api_tool.py) are in /app
+CMD ["fast-agent", "serve", "--card", "agent.md", "--transport", "http", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,27 @@
 ---
-title: Agent Test
-emoji: 📚
-colorFrom: gray
-colorTo: yellow
+title: Fast Agent Demo
+emoji: 🤖
+colorFrom: blue
+colorTo: green
 sdk: docker
-pinned: false
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Fast Agent on Hugging Face Spaces
+
+This Space runs [fast-agent](https://pypi.org/project/fast-agent-mcp/) with custom tools and agent cards.
+
+The agent is accessible via HTTP API and can be interacted with programmatically.
+
+## Configuration
+
+This Space includes:
+- A custom agent card (`agent.md`) defining the agent's capabilities
+- A Python tool file (`hf_api_tool.py`) for Hugging Face API access
+- Environment-based configuration for tokens
+
+## Usage
+
+Once the Space is running, you can interact with the agent via HTTP requests to the Space URL.
+
+See the [fast-agent documentation](https://github.com/evalstate/fast-agent) for more details.

agent.md

@@ -0,0 +1,33 @@
+---
+type: agent
+name: hf-api-agent
+function_tools:
+  - hf_api_tool.py:hf_api_request
+model: gpt-4
+default: true
+description: An agent with access to Hugging Face API
+---
+
+# Hugging Face API Agent
+
+You are an agent with access to the Hugging Face Hub API via the `hf_api_request` tool.
+
+## Available Tool
+
+**hf_api_request(endpoint, method="GET", params=None, json_body=None, max_results=None)**
+
+Call the Hugging Face Hub API. Examples:
+
+- Get current user info: `hf_api_request(endpoint="/whoami-v2")`
+- Get user overview: `hf_api_request(endpoint="/users/{username}/overview")`
+- List user's liked repos: `hf_api_request(endpoint="/users/{username}/likes")`
+- Get organization info: `hf_api_request(endpoint="/organizations/{org}/overview")`
+
+## Instructions
+
+When users ask about Hugging Face data:
+1. Use the appropriate API endpoint
+2. Format the response in a clear, readable way
+3. If authentication is needed and fails, inform the user they may need to configure HF_TOKEN
+
+Be helpful and concise in your responses.

hf_api_tool.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+DEFAULT_MAX_RESULTS = 20
+DEFAULT_TIMEOUT_SEC = 30
+
+
+def _load_token() -> str | None:
+    token = os.getenv("HF_TOKEN")
+    if token:
+        return token
+
+    token_path = Path.home() / ".cache" / "huggingface" / "token"
+    if token_path.exists():
+        token_value = token_path.read_text(encoding="utf-8").strip()
+        return token_value or None
+
+    return None
+
+
+def _max_results_from_env() -> int:
+    raw = os.getenv("HF_MAX_RESULTS")
+    if not raw:
+        return DEFAULT_MAX_RESULTS
+    try:
+        value = int(raw)
+    except ValueError:
+        return DEFAULT_MAX_RESULTS
+    return value if value > 0 else DEFAULT_MAX_RESULTS
+
+
+def _normalize_endpoint(endpoint: str) -> str:
+    if endpoint.startswith("http://") or endpoint.startswith("https://"):
+        raise ValueError("Endpoint must be a path relative to /api, not a full URL.")
+    endpoint = endpoint.strip()
+    if not endpoint:
+        raise ValueError("Endpoint must be a non-empty string.")
+    if not endpoint.startswith("/"):
+        endpoint = f"/{endpoint}"
+    return endpoint
+
+
+def _normalize_params(params: dict[str, Any] | None) -> dict[str, Any]:
+    if not params:
+        return {}
+    normalized: dict[str, Any] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, (list, tuple)):
+            normalized[key] = [str(item) for item in value]
+        else:
+            normalized[key] = str(value)
+    return normalized
+
+
+def _build_url(endpoint: str, params: dict[str, Any] | None) -> str:
+    base = os.getenv("HF_ENDPOINT", "https://huggingface.co").rstrip("/")
+    url = f"{base}/api{_normalize_endpoint(endpoint)}"
+    normalized_params = _normalize_params(params)
+    if normalized_params:
+        url = f"{url}?{urlencode(normalized_params, doseq=True)}"
+    return url
+
+
+def hf_api_request(
+    endpoint: str,
+    method: str = "GET",
+    params: dict[str, Any] | None = None,
+    json_body: dict[str, Any] | None = None,
+    max_results: int | None = None,
+) -> dict[str, Any]:
+    """
+    Call the Hugging Face Hub API (GET/POST only).
+
+    Args:
+        endpoint: API endpoint relative to /api (e.g. "/whoami-v2").
+        method: HTTP method (GET or POST).
+        params: Optional query parameters.
+        json_body: Optional JSON payload for POST requests.
+        max_results: Max results when response is a list (defaults to HF_MAX_RESULTS).
+
+    Returns:
+        A dict with the response data and request metadata.
+    """
+    method_upper = method.upper()
+    if method_upper not in {"GET", "POST"}:
+        raise ValueError("Only GET and POST are allowed for hf_api_request.")
+
+    if method_upper == "GET" and json_body is not None:
+        raise ValueError("GET requests do not accept json_body.")
+
+    url = _build_url(endpoint, params)
+
+    headers = {
+        "Accept": "application/json",
+    }
+    token = _load_token()
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    data = None
+    if method_upper == "POST":
+        headers["Content-Type"] = "application/json"
+        data = json.dumps(json_body or {}).encode("utf-8")
+
+    request = Request(url, headers=headers, data=data, method=method_upper)
+
+    try:
+        with urlopen(request, timeout=DEFAULT_TIMEOUT_SEC) as response:
+            raw = response.read()
+            status_code = response.status
+    except HTTPError as exc:
+        error_body = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(
+            f"HF API error {exc.code} for {url}: {error_body}"
+        ) from exc
+    except URLError as exc:
+        raise RuntimeError(f"HF API request failed for {url}: {exc}") from exc
+
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        payload = raw.decode("utf-8", errors="replace")
+
+    if isinstance(payload, list):
+        limit = max_results if max_results is not None else _max_results_from_env()
+        payload = payload[: max(limit, 0)]
+
+    return {
+        "url": url,
+        "status": status_code,
+        "data": payload,
+    }