Gemini Starter Agent

Gemini Starter Agent is a Python CLI that scaffolds AI agent projects using the OpenAI Agents SDK with OpenAI-compatible providers. It currently supports Gemini, Groq, and xAI (Grok), creates a UV-managed project, installs runtime dependencies, and generates a ready-to-run agent template.

Features

• Bootstrap a new AI agent project from one CLI command.
• Choose Gemini, Groq, or xAI (Grok) during setup.
• Select a default model or enter a custom OpenAI-compatible model name.
• Create a new project folder or write into the current directory with ..
• Generate .env, src/<package>/main.py, and pyproject.toml script entries.
• Install openai-agents and python-dotenv into the generated project with UV.

Installation

pip install gemini-starter-agent

The package installs this console command:

gemini-starter-agent

Usage

Create a new project folder:

gemini-starter-agent my-agent

Use the current directory and skip the project-name prompt:

gemini-starter-agent .

Run interactively and enter the project name when prompted:

gemini-starter-agent

If the current directory is not empty and you use ., the CLI asks for confirmation before writing files.

CLI Prompts

Depending on the command, you will be asked for:

• Project name, unless passed as my-agent or ..
• Provider: Gemini, Groq, or xAI.
• Provider API key.
• Model selection or a custom model.
• Agent name.
• Agent instructions/purpose.

Provider Defaults

Gemini

Base URL:

https://generativelanguage.googleapis.com/v1beta/openai/

Models:

• gemini-2.0-flash
• gemini-2.5-flash
• Custom model

Groq

Base URL:

https://api.groq.com/openai/v1

Models:

• llama-3.1-8b-instant
• llama-3.3-70b-versatile
• openai/gpt-oss-20b
• Custom model

xAI (Grok)

Base URL:

https://api.x.ai/v1

Models:

• grok-4
• grok-4-mini
• grok-4.5
• Custom model

Generated Project Structure

your-project-name/
|-- src/
|   `-- your_project_name/
|       |-- __init__.py
|       `-- main.py
|-- .env
|-- pyproject.toml
`-- uv.lock

When you run openai-compatible-agent ., these files are created directly in the current directory instead of a nested folder.

Generated Environment Variables

Example Groq .env:

PROVIDER=groq
API_KEY=your_api_key_here
MODEL=llama-3.3-70b-versatile
BASE_URL=https://api.groq.com/openai/v1

Example Gemini .env:

PROVIDER=gemini
API_KEY=your_api_key_here
MODEL=gemini-2.5-flash
BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/

Example xAI .env:

PROVIDER=xai
API_KEY=your_api_key_here
MODEL=grok-4
BASE_URL=https://api.x.ai/v1

Running Your Generated Agent

If you created a new folder, change into it:

cd my-agent

Run the script printed by the CLI:

uv run helpful-assistant

The CLI also adds a project-prefixed script name, for example:

uv run my-agent-helpful-assistant

Example Generated main.py

import asyncio
import os
from dotenv import load_dotenv
from agents import Agent, Runner, RunConfig, OpenAIChatCompletionsModel, set_tracing_disabled
from openai import AsyncOpenAI

load_dotenv()

set_tracing_disabled(True)

client: AsyncOpenAI = AsyncOpenAI(api_key=os.getenv("API_KEY"), base_url=os.getenv("BASE_URL"))
model: OpenAIChatCompletionsModel = OpenAIChatCompletionsModel(os.getenv("MODEL"), client)

agent: Agent = Agent(
    name="Helpful Assistant",
    instructions="You're a helpful assistant, help user with any query",
    model=model,
)

async def main() -> None:
    prompt = "What is Agentic AI? The output format should be in haiku"
    result = await Runner.run(agent, prompt, run_config=RunConfig(model))
    print(result.final_output)


def start():
    asyncio.run(main())

Local Development

pip install -e .
python -m py_compile gemini_starter_agent/main.py
gemini-starter-agent .

Build release artifacts locally:

python setup.py sdist bdist_wheel

Notes

• uv must be installed and available on PATH because the CLI runs uv init, uv venv, and uv add.
• Do not commit generated .env files or real provider API keys.

License

This project is licensed under the MIT License. See LICENSE.md.

Author

Marjan Ahmed

• Email: marjanahmed.dev@gmail.com
• GitHub: https://github.com/marjan-ahmed