Spaces:

MCP-1st-Birthday
/

eu-ai-act-compliance-agent

Running

App Files Files Community

eu-ai-act-compliance-agent / apps /eu-ai-act-agent /QUICKSTART.md

drosatos

Deploy

fdcac99 8 days ago

preview code

raw

history blame contribute delete

8.48 kB

🚀 Quick Start Guide

Get the EU AI Act Compliance Agent running in under 5 minutes!

⚡ Fast Track

# 1. Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Set your API keys (required)
export TAVILY_API_KEY="tvly-your-tavily-key"  # Required - Get from https://app.tavily.com
# Choose one model and set its API key:
export ANTHROPIC_API_KEY="sk-ant-your-key"    # For Claude 4-5
# OR
export OPENAI_API_KEY="sk-your-key"           # For GPT-5
# OR
export XAI_API_KEY="xai-your-key"             # For Grok 4-1

# 3. Install dependencies (from workspace root)
cd /path/to/mcp-1st-birthday-ai-act
pnpm install

# 4. Install Python packages
cd apps/eu-ai-act-agent
uv pip install -r requirements.txt

# 5. Start everything (automatic!)
chmod +x start.sh
./start.sh

That's it! Open http://localhost:7860 🎉

📋 Step-by-Step Instructions

1. Prerequisites

Install these first:

Node.js 18+: https://nodejs.org/
pnpm: npm install -g pnpm
Python 3.9+: https://www.python.org/
uv: https://docs.astral.sh/uv/ (fast Python package manager)
Git: https://git-scm.com/

2. Get API Keys

Tavily (Required):

Sign up at https://app.tavily.com
Get your API key (1,000 free credits/month)
Copy it (starts with tvly-)

Model Selection (Required - Choose One):

Option A: Claude 4-5 (Anthropic):

Sign up at https://console.anthropic.com/
Go to API Keys section
Create a new key
Copy it (starts with sk-ant-)

Option B: GPT-5 (OpenAI):

Sign up at https://platform.openai.com/
Go to API Keys section
Create a new key
Copy it (starts with sk-)

Option C: Grok 4-1 (xAI):

Sign up at https://x.ai/
Go to API Keys section
Create a new key
Copy it (starts with xai-)

3. Clone & Setup

# Clone the repository
git clone <repo-url>
cd mcp-1st-birthday-ai-act

# Install Node.js dependencies
pnpm install

# Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Go to agent directory
cd apps/eu-ai-act-agent

# Install Python dependencies
uv pip install -r requirements.txt

4. Configure Environment

Create .env file in the workspace root (not in apps/eu-ai-act-agent):

# Go back to workspace root
cd ../..

# Create .env file
cat > .env << EOF
# Required: Tavily API key
TAVILY_API_KEY=tvly-your-tavily-api-key-here

# Required: Choose one model and provide its API key
# For Claude 4-5:
ANTHROPIC_API_KEY=sk-ant-your-key-here
# OR for GPT-5:
OPENAI_API_KEY=sk-your-openai-api-key-here
# OR for Grok 4-1:
XAI_API_KEY=xai-your-key-here

PORT=3001
EOF

Or copy from example:

cp .env.example .env
# Then edit .env with your keys

5. Build MCP Server

The agent needs the MCP server tools:

# From workspace root
pnpm --filter @eu-ai-act/mcp-server build

6. Start the Agent

Option A: Use startup script (easiest)

cd apps/eu-ai-act-agent
chmod +x start.sh
./start.sh

Option B: Manual start (two terminals)

Terminal 1 - API Server:

cd apps/eu-ai-act-agent
pnpm dev

Terminal 2 - Gradio UI:

cd apps/eu-ai-act-agent
uv run src/gradio_app.py

Option C: Use workspace commands

# Terminal 1
pnpm --filter @eu-ai-act/agent dev

# Terminal 2
pnpm --filter @eu-ai-act/agent gradio

7. Open the UI

Navigate to http://localhost:7860 in your browser!

🎯 Try It Out

Example 1: General Question

You: What is the EU AI Act?

The agent will explain the regulation with key details.

Example 2: Organization Analysis

You: Analyze OpenAI's EU AI Act compliance

The agent will:

Discover OpenAI's organization profile
Identify their AI systems
Assess compliance status
Provide recommendations

Example 3: Risk Classification

You: Is a recruitment screening AI high-risk?

The agent will classify it per Annex III and explain requirements.

Example 4: Documentation

You: Generate compliance documentation for a chatbot

The agent will create:

Risk assessment
Technical documentation
Transparency notice
Compliance checklist

🔧 Troubleshooting

"Cannot connect to API server"

Solution:

# Check if API is running
curl http://localhost:3001/health

# If not, start it:
cd apps/eu-ai-act-agent
pnpm dev

"API key error" or "Model not found"

Solution:

# Verify your Tavily API key is set
echo $TAVILY_API_KEY

# Verify your model API key is set (check which one you're using)
echo $ANTHROPIC_API_KEY  # For Claude 4-5
echo $OPENAI_API_KEY     # For GPT-5
echo $XAI_API_KEY        # For Grok 4-1

# Or check .env file
cat ../../.env | grep -E "(TAVILY|ANTHROPIC|OPENAI|XAI)_API_KEY"

# Make sure your API keys are valid:
# - Tavily: https://app.tavily.com
# - Claude: https://console.anthropic.com/api-keys
# - OpenAI: https://platform.openai.com/api-keys
# - xAI: https://x.ai/api-keys

"Module not found" errors

Solution:

# Reinstall Node.js dependencies
cd /path/to/workspace/root
pnpm install

# Rebuild MCP server
pnpm --filter @eu-ai-act/mcp-server build

# Reinstall Python packages
cd apps/eu-ai-act-agent
pip3 install -r requirements.txt

Port already in use

Solution:

# API Server (port 3001)
PORT=3002 pnpm dev

# Gradio (port 7860) - edit src/gradio_app.py
# Change server_port=7860 to server_port=7861

Python package issues

Solution:

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies with uv
uv pip install -r requirements.txt

# Or create and use a virtual environment with uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

📊 What's Included

Three MCP Tools

discover_organization - Profile organizations
- Company research via Tavily
- AI maturity assessment
- Regulatory context
discover_ai_services - Catalog AI systems
- Risk classification (Unacceptable/High/Limited/Minimal)
- Compliance status
- Gap analysis
assess_compliance - Generate documentation
- Risk management templates
- Technical documentation
- Conformity assessments
- Transparency notices

Intelligent Features

Natural Language: Chat in plain English
Contextual: Remembers conversation history
Multi-Step: Automatically chains tools
Streaming: Real-time responses
Export: Download generated documents

🎓 Learning Path

Start Simple: Ask "What is the EU AI Act?"
Try Classification: "Is [your AI] high-risk?"
Explore Tools: "Discover [company name]"
Generate Docs: "Create compliance documentation"
Go Deep: Ask about specific Articles or requirements

📚 Next Steps

Read the full README: cat README.md
Check deployment guide: cat DEPLOYMENT.md
Explore the MCP tools: See ../../packages/eu-ai-act-mcp/README.md
Learn about Vercel AI SDK: https://ai-sdk.dev/docs
Understand Gradio: https://gradio.app/guides/quickstart

💡 Tips

Be specific: "Analyze compliance for our recruitment AI" works better than "check compliance"
Use context: Mention company names, AI system types, industries
Ask follow-ups: The agent maintains conversation context
Request docs: Ask for specific templates or reports
Cite articles: Reference specific AI Act articles for detailed info

🆘 Getting Help

📖 Full Documentation: See README.md
🐛 Found a bug?: Open a GitHub issue
💬 Questions?: Check GitHub Discussions
📧 Contact: See package.json for maintainer info

🎯 Pro Tips

For Developers

Use pnpm dev for hot reload during development
Check /api/tools endpoint to see available tools
API logs show tool execution details
Gradio supports custom CSS theming

For Compliance Teams

Start with organization discovery
Document all AI systems systematically
Focus on high-risk systems first
Export and archive assessment reports
Review compliance quarterly

For Organizations

Use as part of compliance workflow
Train teams on EU AI Act basics
Generate documentation templates
Track compliance progress
Prepare for audits

Ready to go? Open http://localhost:7860 and start chatting! 🚀