--secrets flag. This guide explains how to map secrets to environment variables for supported agent frameworks and how to retrieve those values at runtime.
Before you start
- Create the required secrets in your organization. Each secret maps a
path(the secret name) to one or morekeyentries. - Ensure
snctlis configured for the target tenant and namespace. - Decide which environment variable names your agent framework expects (see the sections below).
Secret mapping syntax
When you submit or update an agent, pass provider credentials with the--secrets flag. The JSON payload follows this structure:
ENV_NAMEbecomes an environment variable inside the agent runtime. You can also access the same value throughAgentContext.current().get_secret("ENV_NAME").pathreferences the StreamNative secret name, andkeyselects the field within that secret.- Provide multiple entries in the JSON object to surface several credentials at once.
Google agent development kit secrets
Google’s Agent Development Kit (ADK) uses thegoogle-genai SDK, which respects the following environment variables:
GOOGLE_API_KEY—API key for the Gemini Developer API.GEMINI_API_KEY—legacy alias; the runtime prefersGOOGLE_API_KEYwhen both are present.GOOGLE_GENAI_USE_VERTEXAI—set totruewhen you want to call Vertex AI endpoints instead of the public Gemini API.GOOGLE_CLOUD_PROJECT—required for Vertex AI requests.GOOGLE_CLOUD_LOCATION—the Vertex AI region (for example,us-central1).
client = genai.Client() automatically checks these environment variables, no additional configuration is required once the secrets are mapped.
Manage secrets for OpenAI agents
The OpenAI Agents SDK expects the standard OpenAI environment variables:OPENAI_API_KEY—required for all requests.OPENAI_PROJECT—optional project scoping, used when you organize keys by project.OPENAI_ORG_ID—optional organization identifier.OPENAI_BASE_URL—override for custom endpoints such as Azure OpenAI or on-prem gateways.
AgentContext.current().get_secret("OPENAI_API_KEY") inside request handlers instead of reading from os.environ.
Operational tips
- Store non-string data (for example, JSON configs) as base64-encoded strings inside the secret value.
- Rotate provider keys by updating the StreamNative secret; re-run
snctl agents updatewith the same--secretspayload to refresh running agents. - Share secrets across multiple agents by reusing the same
pathwhile pointing each--secretsentry to the appropriatekey. - Document required environment variables alongside your agent code so collaborators know which secret entries to maintain.