ALP Hello Agent

A minimal ALP-compliant agent implementing Agent Load Protocol v0.9.0. Lives in GitHub, deploys automatically via GitHub Actions, secrets managed by GitHub — no manual config.

---

What's inside

hello-agent-alp-kiro/
├── agent.alp.json                   ← ALP v0.9.0 Agent Card (runtime.deploy block)
├── server.py                        ← FastAPI server — /mcp, /agent, /tools, /chat, /health
├── requirements.txt
├── render.yaml                      ← Render deploy config
├── .env                             ← Local secrets (git-ignored)
├── .env.example                     ← Safe template to copy
├── kiro-mcp.json                    ← Paste into .kiro/settings/mcp.json
├── .gitignore
├── knowledge/
│   └── alp-docs.json                ← ALP knowledge base (19 entries, semantic search)
└── .github/
    └── workflows/
        └── deploy.yml               ← GitHub Actions deploy workflow

---

Tools

Tool	Description
greet	Greet a user by name
echo	Echo back any text
get_agent_card	Return the full ALP Agent Card JSON
chat	Send a message to Gemini AI and get a response — callable from Kiro
search_knowledge	Semantic search over the ALP knowledge base using Gemini embeddings
web_search	Search the live web using Serper (Google Search API)

---

GitHub-native deploy (recommended)

This repo follows the ALP v0.9.0 GitHub-native pattern. Secrets stay in GitHub. Deployment is automatic. No manual server setup.

Step 1 — Fork this repo

Fork or clone into your own GitHub account.

Step 2 — Add GitHub Secrets

Go to your repo: Settings → Secrets and variables → Actions → New repository secret

Secret	What it is
GEMINI_API_KEY	Google Gemini API key — free at aistudio.google.com
RENDER_API_KEY	Render API key — Render dashboard → Account → API Keys
RENDER_SERVICE_ID	Render service ID — visible in the Render dashboard URL
SERPER_API_KEY	Serper API key — free at serper.dev (2,500 free queries)

Step 3 — Create the Render service

1. Go to render.com → New → Web Service
2. Connect your GitHub repo
3. Render detects render.yaml automatically
4. Add the GEMINI_API_KEY environment variable in the Render dashboard
5. Copy the service ID from the URL (e.g. srv-xxxxxxxxxxxx) → add as RENDER_SERVICE_ID GitHub Secret
6. Copy your API key from Render Account settings → add as RENDER_API_KEY GitHub Secret

Step 4 — Push to main

The deploy workflow triggers automatically on every push to main that touches agent.alp.json, server.py, or requirements.txt.

You can also trigger it manually: Actions → Deploy ALP Agent → Run workflow

Step 5 — Load in Kiro

Once deployed:

1. Open Kiro
2. Connect GitHub MCP (one-time OAuth — Kiro will prompt you)
3. Say: "Load my agent from github.com/YOUR-USERNAME/hello-agent-alp-kiro"
4. Kiro reads agent.alp.json via GitHub MCP (get_file_contents)
5. Kiro triggers the deploy workflow via workflow_dispatch
6. GitHub Actions deploys with secrets injected
7. Kiro connects to /mcp — chat with your agent

---

Run locally

git clone https://github.com/RodrigoMvs123/hello-agent-alp-kiro
cd hello-agent-alp-kiro

pip install -r requirements.txt
cp .env.example .env        # then add your GEMINI_API_KEY
python server.py

Server starts at http://localhost:8000 — open the dashboard for all links.

---

Live Demo

Endpoint	URL
Dashboard	https://hello-agent-alp-kiro.onrender.com/
Health	https://hello-agent-alp-kiro.onrender.com/health
Agent Card	https://hello-agent-alp-kiro.onrender.com/agent
MCP	https://hello-agent-alp-kiro.onrender.com/mcp
Chat UI	https://hello-agent-alp-kiro.onrender.com/chat-ui

---

Endpoints

Endpoint	Description
GET /	Dashboard
GET /health	{"status": "ok", "alp_version": "0.9.0"}
GET /agent	Full Agent Card JSON
GET /persona	System prompt for any runtime
GET /agents	All hosted agent cards
GET /tools	Tool list (Claude Code / Claude Desktop)
POST /tools/{name}	Execute a tool (greet, echo, get_agent_card, chat, search_knowledge, web_search)
GET /mcp	MCP SSE stream (Kiro)
POST /mcp	MCP JSON-RPC receiver (Kiro)
POST /chat	Gemini chat API
GET /chat-ui	Chat UI in the browser
GET /logs	Last 50 log entries

---

Connect to Kiro

Paste into .kiro/settings/mcp.json:

{
  "mcpServers": {
    "hello-agent": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

For the deployed version replace the URL with https://hello-agent-alp-kiro.onrender.com/mcp.

---

How secrets stay safe

• GitHub Secrets are stored encrypted in your repo
• They are never returned by the GitHub API
• They are injected only into the workflow runner at runtime
• They never appear in agent.alp.json, in logs, or in any config file

---

Protocol

Implements ALP v0.9.0.

License

MIT