--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 morekey
entries. - Ensure
snctl
is 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_NAME
becomes an environment variable inside the agent runtime. You can also access the same value throughAgentContext.current().get_secret("ENV_NAME")
.path
references the StreamNative secret name, andkey
selects 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_KEY
when both are present.GOOGLE_GENAI_USE_VERTEXAI
—set totrue
when 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 update
with the same--secrets
payload to refresh running agents. - Share secrets across multiple agents by reusing the same
path
while pointing each--secrets
entry to the appropriatekey
. - Document required environment variables alongside your agent code so collaborators know which secret entries to maintain.