Simple ReAct agent Agent generated with agents-cli version 0.1.1

my-agent2/
├── app/         # Core agent code
│   ├── agent.py               # Main agent logic
│   └── app_utils/             # App utilities and helpers
├── tests/                     # Unit, integration, and load tests
├── GEMINI.md                  # AI-assisted development guide
└── pyproject.toml             # Project dependencies

💡 Tip: Use Gemini CLI for AI-assisted development - project context is pre-configured in GEMINI.md.

This agent can use Nimble’s hosted MCP server for live web search, extract, crawl, map, and extraction agents, following the Google ADK + Nimble integration pattern (McpToolset + StreamableHTTPConnectionParams).

1. Create an API key in the Nimble dashboard.

2. Export it (or copy .env.example to .env and fill values):

   export NIMBLE_API_KEY="your-nimble-api-key"

When NIMBLE_API_KEY is unset in the Python process, Nimble tools are omitted unless the key arrives on the request as X-Nimble-Api-Key (the Next.js CopilotKit route sends this from my-copilot-app/.env.local). The Python app also loads my-agent2/.env at startup via python-dotenv if you prefer configuring the key there.

Verify: open GET http://127.0.0.1:8000/ (or your AGENT_URL). The JSON field nimble_api_key_process_env is set only when Python’s environment has the key; CopilotKit can still use Nimble when it is absent if Next forwards X-Nimble-Api-Key.

Optional environment variables:

Before you begin, ensure you have:

• uv: Python package manager (used for all dependency management in this project) - Install (add packages with uv add <package>)
• agents-cli: Agents CLI - Install with uv tool install google-agents-cli
• Google Cloud SDK: For GCP services - Install

The agent is exposed as a FastAPI app with AG-UI (ag-ui-adk): ADKAgent wraps root_agent, and add_adk_fastapi_endpoint mounts the run endpoint at POST / plus GET /capabilities. This project also registers POST /capabilities (some clients probe capabilities with POST; the stock ADK mount is GET-only and would otherwise return 405). The combined ASGI app (including POST /feedback) is loaded via app.fast_api_app:app for Docker and uvicorn.

Run locally:

uv run uvicorn app.fast_api_app:app --reload --host localhost --port 8000
# or: uv run python -m app.agent

Optional environment variables (defaults match the prior ADK app name app):

CopilotKit / Next.js: If the browser talks to this API on another origin (e.g. Next on port 3000 and HttpAgent pointed at 8000), the browser sends a CORS OPTIONS preflight before POST /. Without CORS, that often surfaces as HTTP 405 Method Not Allowed. app.fast_api_app registers CORSMiddleware for http://localhost:3000 and http://127.0.0.1:3000 by default. Set ALLOW_ORIGINS to a comma-separated list to add or replace origins (e.g. your deployed app URL).

In the usual CopilotKit setup, runtimeUrl is your Next.js handler (e.g. /api/copilotkit), and CopilotRuntime maps agent ids to HttpAgent URLs (same pattern as the tool-based Gen UI demo).

This repo exposes:

Set AGENT_URL in the Next.js environment (my-copilot-app, default http://127.0.0.1:8000) if the Python server differs. Use no trailing slash on AGENT_URL itself; the CopilotKit route builds {AGENT_URL}/gen-ui-tool-based/ for the Gen UI agent.

The dedicated Gen UI agent is mounted at POST /gen-ui-tool-based/ (trailing slash). Clients that POST to /gen-ui-tool-based without the slash receive a 307 redirect to the slash URL so CopilotKit’s HttpAgent does not see a FastAPI 404.

For tool-based Generative UI (useComponent in the browser), the ADK agent must include AGUIToolset() in its tools list. ag-ui-adk replaces that placeholder each run with ClientProxyToolset, wiring RunAgentInput.tools from CopilotKit (your render_* tools) into Gemini. Without AGUIToolset, the model never receives those frontend tools and cannot call them.

File uploads: BusinessResearchShell enables CopilotKit v2 attachments (drag-and-drop, file picker, clipboard paste in the chat area). Files are inlined as AG-UI multimodal parts; ag_ui_adk maps them to Gemini types.Part (see convert_message_content_to_parts in ag-ui-adk). Default max size is 20 MB per file (accept: "*/*").

Post-upload follow-ups: Welcome pills still come from useConfigureSuggestions (before-first-message) in suggestions.tsx. ResearchCopilotChatView (the CopilotChat chatView slot) shows upload follow-ups as soon as files are staged or after an upload-backed message. While you are still on the welcome screen with staged files, the strip lists only the four upload-specific pills so the same five defaults are not duplicated under the built-in welcome row. After a file is in the thread, the strip shows only those four (defaults were already available earlier). Pills call onSubmitMessage so staged files merge like Send. threadHasUpload drives in-thread detection. CopilotChatConfigurationProvider in BusinessResearchShell keeps hook context aligned with CopilotChat.

The ADK App object is still available as adk_app from app.agent (or from app import adk_app) for runners and tooling.

Install required packages:

agents-cli install

Test the agent with a local web server (AG-UI FastAPI):

uv run uvicorn app.fast_api_app:app --reload --host localhost --port 8000

Note: agents-cli playground expects the stock ADK get_fast_api_app layout. This project serves AG-UI from app/agent.py and mounts extra routes in app/fast_api_app.py, so prefer uvicorn as above for local HTTP.

You can also use features from the ADK CLI with uv run adk.

Edit your agent logic in app/agent.py and test with agents-cli playground - it auto-reloads on save.

gcloud config set project <your-project-id>
agents-cli deploy

To add CI/CD and Terraform, run agents-cli scaffold enhance. To set up your production infrastructure, run agents-cli infra cicd.

Built-in telemetry exports to Cloud Trace, BigQuery, and Cloud Logging.