Spaces:
Running
Running
Delete DEPLOYMENT.md
Browse files- DEPLOYMENT.md +0 -187
DEPLOYMENT.md
DELETED
|
@@ -1,187 +0,0 @@
|
|
| 1 |
-
# Deploying Fast-Agent to Hugging Face Spaces
|
| 2 |
-
|
| 3 |
-
## Quick Start
|
| 4 |
-
|
| 5 |
-
This directory contains everything you need to deploy fast-agent to a Hugging Face Space.
|
| 6 |
-
|
| 7 |
-
## Files Overview
|
| 8 |
-
|
| 9 |
-
- **README.md**: Space metadata and description (with YAML header)
|
| 10 |
-
- **Dockerfile**: Docker image definition (Python 3.13 + uv)
|
| 11 |
-
- **agent.md**: Agent card defining the agent's capabilities and tools
|
| 12 |
-
- **hf_api_tool.py**: Python tool for HF API access (from fast-agent examples)
|
| 13 |
-
- **.gitignore**: Files to ignore in git
|
| 14 |
-
|
| 15 |
-
## Deployment Steps
|
| 16 |
-
|
| 17 |
-
### 1. Create a New Space
|
| 18 |
-
|
| 19 |
-
Go to https://huggingface.co/new-space and:
|
| 20 |
-
- Choose a name for your Space
|
| 21 |
-
- Select **Docker** as the SDK
|
| 22 |
-
- Choose visibility (Public or Private)
|
| 23 |
-
- Click "Create Space"
|
| 24 |
-
|
| 25 |
-
### 2. Clone Your Space Repository
|
| 26 |
-
|
| 27 |
-
```bash
|
| 28 |
-
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
|
| 29 |
-
cd YOUR_SPACE_NAME
|
| 30 |
-
```
|
| 31 |
-
|
| 32 |
-
### 3. Copy Files
|
| 33 |
-
|
| 34 |
-
Copy all files from this directory to your Space repository:
|
| 35 |
-
|
| 36 |
-
```bash
|
| 37 |
-
cp /path/to/this/directory/* YOUR_SPACE_NAME/
|
| 38 |
-
```
|
| 39 |
-
|
| 40 |
-
Or manually copy:
|
| 41 |
-
- README.md
|
| 42 |
-
- Dockerfile
|
| 43 |
-
- agent.md
|
| 44 |
-
- hf_api_tool.py
|
| 45 |
-
- .gitignore
|
| 46 |
-
|
| 47 |
-
### 4. Commit and Push
|
| 48 |
-
|
| 49 |
-
```bash
|
| 50 |
-
git add .
|
| 51 |
-
git commit -m "Initial fast-agent deployment"
|
| 52 |
-
git push
|
| 53 |
-
```
|
| 54 |
-
|
| 55 |
-
### 5. Wait for Build
|
| 56 |
-
|
| 57 |
-
Hugging Face will automatically:
|
| 58 |
-
- Build the Docker image (Python 3.13 + uv)
|
| 59 |
-
- Deploy the container
|
| 60 |
-
- Make it available at your Space URL
|
| 61 |
-
|
| 62 |
-
This usually takes 2-5 minutes.
|
| 63 |
-
|
| 64 |
-
### 6. (Optional) Add Secrets
|
| 65 |
-
|
| 66 |
-
If your agent needs authentication:
|
| 67 |
-
|
| 68 |
-
1. Go to your Space settings
|
| 69 |
-
2. Navigate to "Repository secrets"
|
| 70 |
-
3. Add `HF_TOKEN` with your Hugging Face token
|
| 71 |
-
4. Restart the Space
|
| 72 |
-
|
| 73 |
-
## Testing Locally
|
| 74 |
-
|
| 75 |
-
Before deploying, you can test locally:
|
| 76 |
-
|
| 77 |
-
```bash
|
| 78 |
-
# Build the Docker image
|
| 79 |
-
docker build -t fast-agent-space .
|
| 80 |
-
|
| 81 |
-
# Run it locally
|
| 82 |
-
docker run -p 7860:7860 -e HF_TOKEN=your_token fast-agent-space
|
| 83 |
-
|
| 84 |
-
# Test the endpoint
|
| 85 |
-
curl http://localhost:7860
|
| 86 |
-
```
|
| 87 |
-
|
| 88 |
-
## Technical Details
|
| 89 |
-
|
| 90 |
-
### Python & Dependencies
|
| 91 |
-
|
| 92 |
-
- **Python 3.13**: Using the latest slim image
|
| 93 |
-
- **uv**: Astral's fast Python package installer
|
| 94 |
-
- **System packages**: bash, git, git-lfs, wget, curl, procps
|
| 95 |
-
|
| 96 |
-
The Dockerfile uses `uv pip install --system` for faster, more reliable package installation.
|
| 97 |
-
|
| 98 |
-
## Customization
|
| 99 |
-
|
| 100 |
-
### Change the Agent Card
|
| 101 |
-
|
| 102 |
-
Edit `agent.md` to modify:
|
| 103 |
-
- Agent name
|
| 104 |
-
- Model (e.g., `gpt-4`, `claude-3-sonnet`, etc.)
|
| 105 |
-
- Instructions
|
| 106 |
-
- Tool references
|
| 107 |
-
|
| 108 |
-
### Add More Tools
|
| 109 |
-
|
| 110 |
-
1. Create a new Python file (e.g., `my_tool.py`)
|
| 111 |
-
2. Add your tool function
|
| 112 |
-
3. Reference it in `agent.md`:
|
| 113 |
-
```yaml
|
| 114 |
-
function_tools:
|
| 115 |
-
- hf_api_tool.py:hf_api_request
|
| 116 |
-
- my_tool.py:my_function
|
| 117 |
-
```
|
| 118 |
-
|
| 119 |
-
### Multiple Agent Cards
|
| 120 |
-
|
| 121 |
-
Modify the Dockerfile CMD to include multiple cards:
|
| 122 |
-
|
| 123 |
-
```dockerfile
|
| 124 |
-
CMD ["fast-agent", "serve", "--card", "agent1.md", "--card", "agent2.md", "--port", "7860"]
|
| 125 |
-
```
|
| 126 |
-
|
| 127 |
-
### Change the Model
|
| 128 |
-
|
| 129 |
-
Add `--model` to the CMD in Dockerfile:
|
| 130 |
-
|
| 131 |
-
```dockerfile
|
| 132 |
-
CMD ["fast-agent", "serve", "--card", "agent.md", "--model", "gpt-4", "--port", "7860"]
|
| 133 |
-
```
|
| 134 |
-
|
| 135 |
-
### Additional Dependencies
|
| 136 |
-
|
| 137 |
-
If you need extra Python packages, add them after the fast-agent-mcp install:
|
| 138 |
-
|
| 139 |
-
```dockerfile
|
| 140 |
-
RUN uv pip install --system --no-cache fast-agent-mcp my-package another-package
|
| 141 |
-
```
|
| 142 |
-
|
| 143 |
-
Or use a requirements.txt:
|
| 144 |
-
|
| 145 |
-
```dockerfile
|
| 146 |
-
COPY requirements.txt .
|
| 147 |
-
RUN uv pip install --system --no-cache -r requirements.txt
|
| 148 |
-
```
|
| 149 |
-
|
| 150 |
-
## Accessing Your Agent
|
| 151 |
-
|
| 152 |
-
Once deployed, your agent will be accessible as an HTTP API at:
|
| 153 |
-
```
|
| 154 |
-
https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space
|
| 155 |
-
```
|
| 156 |
-
|
| 157 |
-
You can interact with it via HTTP requests or use it as an MCP server.
|
| 158 |
-
|
| 159 |
-
## Troubleshooting
|
| 160 |
-
|
| 161 |
-
### Space Won't Build
|
| 162 |
-
|
| 163 |
-
Check the build logs in your Space for errors. Common issues:
|
| 164 |
-
- Missing dependencies in Dockerfile
|
| 165 |
-
- Syntax errors in agent.md
|
| 166 |
-
- Tool file not found
|
| 167 |
-
|
| 168 |
-
### Space Runs But Errors
|
| 169 |
-
|
| 170 |
-
Check the application logs. Common issues:
|
| 171 |
-
- Model API key not configured
|
| 172 |
-
- Port mismatch (must be 7860)
|
| 173 |
-
- Tool import errors
|
| 174 |
-
|
| 175 |
-
### Need More Resources
|
| 176 |
-
|
| 177 |
-
If you need more CPU/RAM:
|
| 178 |
-
1. Go to Space settings
|
| 179 |
-
2. Upgrade to a paid tier
|
| 180 |
-
3. Select appropriate hardware
|
| 181 |
-
|
| 182 |
-
## Support
|
| 183 |
-
|
| 184 |
-
- Fast-Agent GitHub: https://github.com/evalstate/fast-agent
|
| 185 |
-
- Fast-Agent PyPI: https://pypi.org/project/fast-agent-mcp/
|
| 186 |
-
- Hugging Face Spaces docs: https://huggingface.co/docs/hub/spaces
|
| 187 |
-
- Astral uv docs: https://docs.astral.sh/uv/
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|