agentic-uber

name	agentic-uber
description	Project conventions for agentic-uber — Go ADK console agent, real Uber Riders API, configurable LLM (OpenCode / OpenAI / Gemini), MarketplaceAdapter, action log, and confirmation gates.
paths	["**/*.go","cmd/**","internal/**","scenarios/**","docs/**"]

agentic-uber

Cursor skills vs ADK SkillToolset

• Cursor agent skills live in .agents/skills/ and .cursor/skills/ (this repo).
• ADK SkillToolset (runtime filesystem skills) is out of scope for the 48h MVP unless explicitly requested.
• Do not confuse the two when scaffolding.

Source of truth (Go ADK)

When writing or changing ADK code, follow this order:

1. Pinned google.golang.org/adk examples — see references/adk-go-ground-truth.md
2. adk.dev Go documentation
3. Installed skill .agents/skills/google-adk/reference/**/*-go.md sidecars only
4. Never copy Python/TypeScript ADK snippets (LlmAgent, FunctionTool(require_confirmation=True), etc.)

For tool confirmation concepts (not Go API), you may read action-confirmations.md; implement using Go functiontool + toolconfirmation APIs only.

Mandatory ADK reference paths

Task	Read first
Console launcher	.agents/skills/google-adk/reference/runtime/command-line.md, reference/getting-started/go-quickstart.md
Function tools	reference/tools/function-tools-overview-go.md
Book/cancel confirm	references/adk-go-ground-truth.md → adk-go/examples/toolconfirmation; then action-confirmations.md (concepts)
Sessions	reference/sessions/state-go.md, reference/sessions/memory-go.md
MCP (optional)	reference/tools/mcp-tools-go.md
Tool auth (defer)	reference/tools/tool-authentication-go.md — use file OAuth until adk-go#574

Entry and runtime

• CLI entry: full.NewLauncher() → subcommand console (not a custom Bubble Tea TUI).
• Session options: adk.dev command-line / session options (--save_session, --resume, --replay).
• Sessions: session.InMemoryService only for MVP (tool confirmation constraints).
• Transcripts: console --replay scenarios/*.json with { "state": {}, "queries": [...] }.

LLM (configurable)

Select backend with LLM_PROVIDER (opencode | openai | gemini). Wire only via internal/model.NewFromEnv(ctx) — do not import provider SDKs in internal/agent.

Provider	Env	Default model
opencode (default)	OPENCODE_GO_API_KEY, optional LLM_BASE_URL	deepseek-v4-pro
openai	OPENAI_API_KEY or LLM_API_KEY	gpt-4o-mini
gemini	GOOGLE_API_KEY or GEMINI_API_KEY	gemini-2.5-flash

Shared: LLM_MODEL overrides default for any provider. See .env.example.

OpenCode and OpenAI use github.com/huytd/adk-openai-go (OpenAI-compatible). Gemini uses google.golang.org/adk/model/gemini. Do not add Anthropic/Alibaba clients in the MVP.

Confirmations and action log

• Mutating tools book_ride, cancel_ride: ADK tool confirmation (RequireConfirmation and/or ctx.RequestConfirmation).
• No custom stdin confirmation loops — the ADK console handles HITL.
• BookingService JSONL action log phases: requested → verified → executed → outcome (or denied).

Uber OAuth (self-managed)

• Token file: data/uber_tokens.json — must be gitignored (never commit tokens).
• Do not use ADK request_credential for Uber until Go parity (adk-go#574).
• Developer app: prefer 3PL Consumer APIs suite; request scopes request, profile, offline_access.
• Sandbox auth/API: https://sandbox-api.uber.com / login sandbox host per Uber docs.
• Production: https://api.uber.com when scopes approved.
• If OAuth returns invalid_scope: fix dashboard suite + Request Scopes before changing code; run doctor CLI when implemented.

Pluggability

• MarketplaceAdapter interface + MARKETPLACE env (uber, lyft, …).
• No mock marketplace in production paths; CI may use httptest + JSON fixtures only.
• MCP (cmd/ride-mcp) is optional and not required for the console agent.

Related skills

• /google-adk — ADK reference (load *-go.md sidecars per table above).
• Go style: go-style-core, go-error-handling, go-context, go-testing, go-interfaces.

Architecture pointer

See .cursor/plans/agentic_uber_system_a01e4d65.plan.md for full system design.