agents-cli Documentation

The agents-cli currently supports the adk template (Python).

• A2A (Agent-to-Agent): Built into every adk agent; the standalone adk_a2a template is now merged into adk.
• RAG (Retrieval-Augmented Generation): There is no longer a dedicated agentic_rag template. Instead, use the rag-vector-search or rag-agent-search samples as a 'clone-and-study' recipe.
• Planned Support: Support for adk_go, adk_java, adk_ts, adk_live, and custom_a2a is planned for future releases.

Scaffolded projects automatically provision infrastructure to route GenAI inference logs and feedback to BigQuery and GCS. This includes:

• Log sinks: Route logs to BigQuery partitioned tables.
• BigQuery dataset: Contains external tables over GCS data and a pre-created log export table.
• GCS logs bucket: Stores completions as NDJSON.
• Completions view: A BigQuery view that joins log export data with GCS-stored prompt/response data.

Log Export Table Names:

• Cloud Run / GKE: gen_ai_client_inference_operation_details
• Agent Runtime: aiplatform_googleapis_com_reasoning_engine_stdout

The Agent Development Kit (ADK) Python uses several fundamental primitives to build agentic systems:

• Agent: The core intelligent unit. Can be an LlmAgent (LLM-driven) or a BaseAgent (custom/workflow).
• Tool: A callable function providing external capabilities (e.g., FunctionTool, AgentTool).
• Session: A stateful conversation thread containing events (history) and state (short-term memory).
• State: A key-value dictionary within a Session used for transient conversation data.
• Runner: The execution engine that orchestrates agent activity and event flow.
• Event: The atomic unit of communication, carrying content and side-effect actions.

Every agents-cli project includes built-in OpenTelemetry instrumentation that automatically exports traces to Cloud Trace. This provides distributed tracing for LLM calls and tool executions, latency analysis, and error visibility without requiring manual configuration.

By default, traces and Cloud Logging events do not contain the actual message content (prompts/responses) to ensure privacy. Content is only captured in traces if OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT is configured to something other than NO_CONTENT and ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS is set to true.

When enabled, the BigQuery Agent Analytics plugin provides the following capabilities:

• Auto-schema upgrade: New fields are added to the schema automatically without requiring manual migrations.
• GCS offloading: Multimodal content such as images and audio is offloaded to Google Cloud Storage.
• Distributed tracing: Integration with OpenTelemetry span context for tracing.
• SQL-queryable event log: All agent interactions are stored in a format that can be queried directly via SQL.

When you run agents-cli create my-agent --prototype --yes, a ready-to-run project is generated. The core structure is as follows:

• app/: Contains your agent code. agent.py is the primary entry point, and __init__.py registers the app.
• tests/: Contains evaluation datasets (tests/eval/datasets/), integration tests (tests/integration/), and unit tests (tests/unit/).
• pyproject.toml: Python project metadata and dependencies.
• agents-cli-manifest.yaml: Metadata for agents-cli commands.
• GEMINI.md: Guidance for AI coding agents.
• .env: Local environment variables.
• Makefile: Shortcut commands like make dev or make eval.

Select a deployment target based on your scaling, networking, and state requirements. All targets are container-based and support any language.

Use the agents-cli publish gemini-enterprise command to register a deployed agent with Gemini Enterprise.

Prerequisites:

1. The agent must be deployed and reachable.
2. A Gemini Enterprise app must already exist in the Google Cloud Console.
3. For Agent Runtime deployments, ensure deployment_metadata.json (generated by agents-cli deploy) is present in the agent directory for auto-detection.

Permissions: If using A2A registration on Cloud Run, you must grant roles/run.servicesInvoker to the Discovery Engine service account: service-<PROJECT_NUMBER>@gcp-sa-discoveryengine.iam.gserviceaccount.com.

Instead of using environment variables for sensitive keys, use GCP Secret Manager. You can pass secrets to Agent Runtime or Cloud Run at deploy time using the --secrets flag.

Format: ENV_VAR=SECRET_ID or ENV_VAR=SECRET_ID:VERSION (defaults to latest).

Accessing in code: Use os.environ.get("ENV_VAR").

Permissions:

• Cloud Run/GKE: Grant secretmanager.secretAccessor to app_sa.
• Agent Runtime: Grant secretmanager.secretAccessor to the platform-managed service account: service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

When you cannot interact with a user (non-interactive runs) or the user provides vague/deferred input (e.g., "you pick", "whatever's standard"), follow these rules:

1. Make a concrete choice.
2. Document it as an assumption. Do not state these choices as facts in the main spec body. Instead, list them under an ## Assumptions heading in the .agents-cli-spec.md file.
3. Surface implicit axes. Always explicitly address:
   • Data sources
   • Auth methods
   • Schedule/cadence
   • Model selection

For non-trivial agents, you must still weigh different approaches and record your decision in the spec, even if the user is not present to guide you.