Turn your README into a live AI demo. Hugging Face Spaces now makes it easy to ship an Agent-powered app, document it in Markdown, and share it with a link.
What’s new: Agents + MD in Spaces
Agents let an LLM plan actions and call tools (functions, models, or APIs). Markdown (MD) keeps your app readme-first, so users see instructions, examples, and a demo in one place.
For a concise overview, see Hugging Face’s guide on Spaces, Agents, and MD (official blog).
5-step quickstart
- Create a Space: Pick Gradio or Streamlit when creating a new Space. It gives you hosted UI, version control, and CI built into the repo (Spaces docs).
- Choose your model: Use Hugging Face Inference (hosted) or call an external provider via API. Start small; upgrade to Inference Endpoints for private, scalable serving.
- Define tools: Wrap safe Python functions (e.g., search, scrape, generate image) and expose only what your agent needs. Keep inputs/outputs simple and validated.
- Assemble the Agent: Give it a clear system prompt, register tools, and enable planning + tool-calling. See Transformers Agents docs for patterns.
- Document with Markdown: Add usage steps, examples, and caveats to README.md. Link to your app UI inside the Space so users can try it immediately.
Great fits
- Interactive docs: Turn tutorials into runnable assistants that fetch data, summarize, or generate images.
- Internal playbooks: One Space per workflow—triage tickets, draft SQL, or QA reports with auditable tool calls.
- Sales demos: Share a single link that showcases real outputs without local setup.
Ship it safely
- Scope tools narrowly; prefer read-only actions and sanitized inputs.
- Log prompts, tool calls, and outputs for debugging and compliance.
- Add usage limits and timeouts to prevent runaway loops or cost surprises.
- Pin model versions and freeze dependencies for reproducibility.
- Disclose limitations in README.md and provide example prompts that work well.
Resources
Start with the Hugging Face blog on Spaces + Agents + MD (read here), the Spaces overview, and Transformers Agents docs for tool-calling patterns.
Takeaway
Combine Agents for action and Markdown for clarity. You’ll ship a trustworthy, readme-first AI app that’s easy to share, test, and maintain—without managing infra.
Enjoy this? Get 2–3 practical AI nuggets weekly. Subscribe to the newsletter.
