TKK_E32230176/Source-Code-Web/.agents/skills/developing-genkit-python/references/dev-workflow.md

Dev Workflow — Genkit Python

Agent responsibility

After generating code, always give the developer:

1. The full pre-run checklist with copy-paste commands using absolute paths
2. The genkit start command to run in their terminal (foreground — it's expected to block)
3. Step-by-step Dev UI instructions so they can test without guessing

Do not offer to run it for them. Give them the commands and let them run it.

---

Step 1 — Get a Gemini API key

If the developer doesn't have one:

Get a free key at https://aistudio.google.com/apikey — click "Create API key", copy it.

---

Step 2 — Set the API key

Open a terminal and run:

export GEMINI_API_KEY=your-api-key-here

To persist across sessions, add it to your shell profile:

echo 'export GEMINI_API_KEY=your-api-key-here' >> ~/.zshrc && source ~/.zshrc

---

Step 3 — Install dependencies

Replace /path/to/your-project with the actual full path to the project (e.g. /Users/yourname/projects/my-genkit-app):

cd /path/to/your-project
uv add genkit genkit-plugin-google-genai

(Requires a project with pyproject.toml — run uv init in an empty directory first if needed.)

---

Step 4 — Start the Dev UI

Run this in your terminal. It will block — that's expected. Leave this terminal open while you use the Dev UI.

cd /path/to/your-project
GEMINI_API_KEY=your-api-key-here genkit start -- uv run src/main.py

You'll see output like:

Genkit Tools UI: http://localhost:4000

The Dev UI is now running at http://localhost:4000

To stop it: press Ctrl+C in the terminal.

---

Step 5 — Test in the Dev UI

1. Open http://localhost:4000 in your browser
2. Click "Run" in the left sidebar
3. Find your flow by name (e.g. summarize, chat, joke_generator)
4. In the input box, paste your input as JSON — e.g:

   {"text": "hello world"}
   

5. Click the "Run" button — the output appears on the right
6. Click "Traces" in the left sidebar to inspect every step, model call, token count, and latency

---

Troubleshooting

Problem	Fix
genkit: command not found	Run: npm install -g genkit-cli
GEMINI_API_KEY not set	Run: export GEMINI_API_KEY=your-key
Port 4000 already in use	Use: genkit start --port 4001 -- uv run src/main.py
uv: command not found	Run: curl -LsSf https://astral.sh/uv/install.sh | sh
Flow not showing in Dev UI	Make sure genkit start output shows no errors