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.
• Friendly error messages for common API issues (invalid key, no credits, rate limits, etc.).

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
import sys
from dotenv import load_dotenv
from agents import Agent, Runner, RunConfig, OpenAIChatCompletionsModel, set_tracing_disabled
from openai import AsyncOpenAI, AuthenticationError, PermissionDeniedError, NotFoundError, RateLimitError, APIConnectionError, APITimeoutError

load_dotenv()

PROVIDER = os.getenv("PROVIDER", "openai-compatible")
MODEL = os.getenv("MODEL")
API_KEY = os.getenv("API_KEY")
BASE_URL = os.getenv("BASE_URL")

if not API_KEY:
    print("ERROR: API_KEY is missing. Add it to your .env file.")
    sys.exit(1)
if not MODEL:
    print("ERROR: MODEL is missing. Add it to your .env file.")
    sys.exit(1)
if not BASE_URL:
    print("ERROR: BASE_URL is missing. Add it to your .env file.")
    sys.exit(1)

set_tracing_disabled(True)

client: AsyncOpenAI = AsyncOpenAI(api_key=API_KEY, base_url=BASE_URL)
model: OpenAIChatCompletionsModel = OpenAIChatCompletionsModel(MODEL, client)

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

PROVIDER_HINTS = {
    "gemini": "Get your key at https://aistudio.google.com/apikey",
    "groq": "Get your key at https://console.groq.com/keys",
    "xai": "Get your key at https://console.x.ai/team/default/api-keys",
}

async def main() -> None:
    prompt = "What is Agentic AI? The output format should be in haiku"
    try:
        result = await Runner.run(agent, prompt, run_config=RunConfig(model))
        print(f"Provider: {PROVIDER}")
        print(result.final_output)
    except AuthenticationError:
        hint = PROVIDER_HINTS.get(PROVIDER, "")
        print(f"\nERROR: Invalid API key for {PROVIDER}.")
        if hint:
            print(f"  -> {hint}")
        print("  -> Check your .env file and make sure the API_KEY is correct.")
        sys.exit(1)
    except PermissionDeniedError as e:
        msg = str(e)
        if "credit" in msg.lower() or "403" in msg:
            print(f"\nERROR: Your {PROVIDER} account has no credits or insufficient permissions.")
            print("  -> Add credits or check your account billing.")
        else:
            print(f"\nERROR: Permission denied: {msg}")
        sys.exit(1)
    except RateLimitError:
        print(f"\nERROR: Rate limit exceeded for {PROVIDER}.")
        print("  -> You're sending too many requests. Wait a moment and try again.")
        sys.exit(1)
    except NotFoundError:
        print(f"\nERROR: Model '{MODEL}' not found on {PROVIDER}.")
        print("  -> Check the model name in your .env file.")
        sys.exit(1)
    except APIConnectionError:
        print(f"\nERROR: Could not connect to {PROVIDER} API at {BASE_URL}.")
        print("  -> Check your internet connection.")
        sys.exit(1)
    except APITimeoutError:
        print(f"\nERROR: Request to {PROVIDER} API timed out.")
        print("  -> The server took too long to respond. Try again later.")
        sys.exit(1)
    except Exception as e:
        print(f"\nERROR: Unexpected error: {e}")
        sys.exit(1)


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