Environments provide isolated execution contexts for running agent code, tools, and services securely.
[View as markdown](https://ai.google.dev/static/api/environments.md.txt) [View the OpenAPI Spec](https://ai.google.dev/static/api/interactions.openapi.json)
> [!NOTE]
> This API is in Beta. Endpoints are under `/v1beta/`.
## CreateEnvironment
post https://generativelanguage.googleapis.com/v1beta/environments Creates an environment.
- [Request body](https://ai.google.dev/api/environments#CreateEnvironment.request_body)
- [Response](https://ai.google.dev/api/environments#CreateEnvironment.response)
### Request body
The request body contains data with the following structure:
network EnvironmentNetworkEgressAllowlist or enum (string) (optional) Network configuration for the environment.
Outbound networking configuration for the sandbox. Accepts an object with an 'allowlist' array to restrict traffic, or the string 'disabled' to turn off all network access. Omit entirely to allow all outbound traffic with no header injection.
#### Possible Types
object Outbound networking configuration for the sandbox. When specified, restricts which external domains the sandbox can reach. Omit entirely to allow all outbound traffic with no header injection.
allowlist array (AllowlistEntry) (optional) List of allowed outbound domains. Only requests to listed domains are permitted. Use \[{'domain': '\*'}\] to allow all domains while still injecting headers on specific ones.
A single domain allowlist rule with optional header injection.
#### Fields
domain string (optional) Domain to allow outbound requests to. Supports wildcards (e.g. '\*.googleapis.com'). Use '\*' to allow all domains.
transform array (object) or object (optional) Headers to inject on all outbound requests matching this domain. Accepts a single dict or a list of dicts. The egress proxy injects these automatically.
string Turns all network off.
#### Possible values
- `disabled`
Turns all network off.
sources array (Source) (optional) Sources to be mounted into the environment.
A source to be mounted into the environment.
#### Fields
content string (optional) The inline content if \`type\` is \`INLINE\`.
encoding string (optional) Optional encoding for inline content (e.g. \`base64\`).
source string (optional) The source of the environment.
For GCS, this is the GCS path.
For GitHub, this is the GitHub path.
target string (optional) Where the source should appear in the environment.
type enum (string) (optional) No description provided.
Possible
values:
- `gcs`
A GCS bucket.
- `inline`
Inline content.
- `repository`
A generic repository. The protocol prefix in the source URL
identifies the provider (e.g., github://, gcs://).
- `skill_registry`
A skill resource from the Skill Registry Service.
Skill: projects/{project}/locations/{location}/skills/{skill}
SkillRevision:
projects/{project}/locations/{location}/skills/{skill}/revisions/{revision}
Support mounting all skills under a project:
projects/{project}/locations/{location}/skills.
### Response
If successful, the response body contains data with the following structure:
created string (optional) Output only. The time at which the environment was created in ISO 8601 format
(YYYY-MM-DDThh:mm:ssZ).
file_count string (optional) Output only. The number of files in the environment, output only.
id string (optional) Required. Output only. The ID of the environment.
last_accessed string (optional) Output only. The time at which the environment was last accessed in ISO 8601 format
(YYYY-MM-DDThh:mm:ssZ).
network EnvironmentNetworkEgressAllowlist or enum (string) (optional) Network configuration for the environment.
Outbound networking configuration for the sandbox. Accepts an object with an 'allowlist' array to restrict traffic, or the string 'disabled' to turn off all network access. Omit entirely to allow all outbound traffic with no header injection.
#### Possible Types
object Outbound networking configuration for the sandbox. When specified, restricts which external domains the sandbox can reach. Omit entirely to allow all outbound traffic with no header injection.
allowlist array (AllowlistEntry) (optional) List of allowed outbound domains. Only requests to listed domains are permitted. Use \[{'domain': '\*'}\] to allow all domains while still injecting headers on specific ones.
A single domain allowlist rule with optional header injection.
#### Fields
domain string (optional) Domain to allow outbound requests to. Supports wildcards (e.g. '\*.googleapis.com'). Use '\*' to allow all domains.
transform array (object) or object (optional) Headers to inject on all outbound requests matching this domain. Accepts a single dict or a list of dicts. The egress proxy injects these automatically.
string Turns all network off.
#### Possible values
- `disabled`
Turns all network off.
size_bytes string (optional) Output only. The total size of the environment files in bytes, output only.
sources array (Source) (optional) Sources to be mounted into the environment.
A source to be mounted into the environment.
#### Fields
content string (optional) The inline content if \`type\` is \`INLINE\`.
encoding string (optional) Optional encoding for inline content (e.g. \`base64\`).
source string (optional) The source of the environment.
For GCS, this is the GCS path.
For GitHub, this is the GitHub path.
target string (optional) Where the source should appear in the environment.
type enum (string) (optional) No description provided.
Possible
values:
- `gcs`
A GCS bucket.
- `inline`
Inline content.
- `repository`
A generic repository. The protocol prefix in the source URL
identifies the provider (e.g., github://, gcs://).
- `skill_registry`
A skill resource from the Skill Registry Service.
Skill: projects/{project}/locations/{location}/skills/{skill}
SkillRevision:
projects/{project}/locations/{location}/skills/{skill}/revisions/{revision}
Support mounting all skills under a project:
projects/{project}/locations/{location}/skills.
status enum (string) (optional) Output only. The status of the environment container.
Possible
values:
- `active`
Output only. The status of the environment container.
- `expired`
Output only. The status of the environment container.
updated string (optional) Output only. The time at which the environment was last updated in ISO 8601 format
(YYYY-MM-DDThh:mm:ssZ).
### Example
#### Example Response
```json
{
"created": "string",
"file_count": "string",
"id": "string",
"last_accessed": "string",
"network": {
"allowlist": [
{
"domain": "github.com",
"transform": [
{
"Authorization": "Bearer your-token"
}
]
},
{
"domain": "*.googleapis.com"
}
]
},
"size_bytes": "string",
"sources": [
{
"content": "string",
"encoding": "string",
"source": "string",
"target": "string",
"type": "gcs"
}
],
"status": "active",
"updated": "string"
}
```
## ListEnvironments
get https://generativelanguage.googleapis.com/v1beta/environments Lists environments.
- [Path / Query parameters](https://ai.google.dev/api/environments#ListEnvironments.PATH_PARAMETERS)
- [Response](https://ai.google.dev/api/environments#ListEnvironments.response)
### Path / Query Parameters
page_size integer (optional) Optional. Maximum number of environments to return.\\nIf unspecified, defaults to 50. Maximum is 1000.
page_token string (optional) Optional. Pagination token.
### Response
If successful, the response body contains data with the following structure:
environments array ([Environment](https://ai.google.dev/api/environments#Resource:Environment)) (optional) Environments belonging to the provided project.
next_page_token string (optional) Pagination token.
### Example
#### Example Response
```json
{
"environments": [
{
"created": "string",
"file_count": "string",
"id": "string",
"last_accessed": "string",
"network": {
"allowlist": [
{
"domain": "github.com",
"transform": [
{
"Authorization": "Bearer your-token"
}
]
},
{
"domain": "*.googleapis.com"
}
]
},
"size_bytes": "string",
"sources": [
{
"content": "string",
"encoding": "string",
"source": "string",
"target": "string",
"type": "gcs"
}
],
"status": "active",
"updated": "string"
}
],
"next_page_token": "string"
}
```
## GetEnvironment
get https://generativelanguage.googleapis.com/v1beta/environments/{id} Gets an environment.
- [Response](https://ai.google.dev/api/environments#GetEnvironment.response)
### Response
If successful, the response body contains data with the following structure:
created string (optional) Output only. The time at which the environment was created in ISO 8601 format
(YYYY-MM-DDThh:mm:ssZ).
file_count string (optional) Output only. The number of files in the environment, output only.
id string (optional) Required. Output only. The ID of the environment.
last_accessed string (optional) Output only. The time at which the environment was last accessed in ISO 8601 format
(YYYY-MM-DDThh:mm:ssZ).
network EnvironmentNetworkEgressAllowlist or enum (string) (optional) Network configuration for the environment.
Outbound networking configuration for the sandbox. Accepts an object with an 'allowlist' array to restrict traffic, or the string 'disabled' to turn off all network access. Omit entirely to allow all outbound traffic with no header injection.
#### Possible Types
object Outbound networking configuration for the sandbox. When specified, restricts which external domains the sandbox can reach. Omit entirely to allow all outbound traffic with no header injection.
allowlist array (AllowlistEntry) (optional) List of allowed outbound domains. Only requests to listed domains are permitted. Use \[{'domain': '\*'}\] to allow all domains while still injecting headers on specific ones.
A single domain allowlist rule with optional header injection.
#### Fields
domain string (optional) Domain to allow outbound requests to. Supports wildcards (e.g. '\*.googleapis.com'). Use '\*' to allow all domains.
transform array (object) or object (optional) Headers to inject on all outbound requests matching this domain. Accepts a single dict or a list of dicts. The egress proxy injects these automatically.
string Turns all network off.
#### Possible values
- `disabled`
Turns all network off.
size_bytes string (optional) Output only. The total size of the environment files in bytes, output only.
sources array (Source) (optional) Sources to be mounted into the environment.
A source to be mounted into the environment.
#### Fields
content string (optional) The inline content if \`type\` is \`INLINE\`.
encoding string (optional) Optional encoding for inline content (e.g. \`base64\`).
source string (optional) The source of the environment.
For GCS, this is the GCS path.
For GitHub, this is the GitHub path.
target string (optional) Where the source should appear in the environment.
type enum (string) (optional) No description provided.
Possible
values:
- `gcs`
A GCS bucket.
- `inline`
Inline content.
- `repository`
A generic repository. The protocol prefix in the source URL
identifies the provider (e.g., github://, gcs://).
- `skill_registry`
A skill resource from the Skill Registry Service.
Skill: projects/{project}/locations/{location}/skills/{skill}
SkillRevision:
projects/{project}/locations/{location}/skills/{skill}/revisions/{revision}
Support mounting all skills under a project:
projects/{project}/locations/{location}/skills.
status enum (string) (optional) Output only. The status of the environment container.
Possible
values:
- `active`
Output only. The status of the environment container.
- `expired`
Output only. The status of the environment container.
updated string (optional) Output only. The time at which the environment was last updated in ISO 8601 format
(YYYY-MM-DDThh:mm:ssZ).
### Example
#### Example Response
```json
{
"created": "string",
"file_count": "string",
"id": "string",
"last_accessed": "string",
"network": {
"allowlist": [
{
"domain": "github.com",
"transform": [
{
"Authorization": "Bearer your-token"
}
]
},
{
"domain": "*.googleapis.com"
}
]
},
"size_bytes": "string",
"sources": [
{
"content": "string",
"encoding": "string",
"source": "string",
"target": "string",
"type": "gcs"
}
],
"status": "active",
"updated": "string"
}
```
## DeleteEnvironment
delete https://generativelanguage.googleapis.com/v1beta/environments/{id} Deletes an environment.
- [Response](https://ai.google.dev/api/environments#DeleteEnvironment.response)
### Response
If successful, the response is empty.
### Example
## Resources
### Environment
An execution environment for an agent.
#### Fields
created string (optional) Output only. The time at which the environment was created in ISO 8601 format
(YYYY-MM-DDThh:mm:ssZ).
file_count string (optional) Output only. The number of files in the environment, output only.
id string (optional) Required. Output only. The ID of the environment.
last_accessed string (optional) Output only. The time at which the environment was last accessed in ISO 8601 format
(YYYY-MM-DDThh:mm:ssZ).
network EnvironmentNetworkEgressAllowlist or enum (string) (optional) Network configuration for the environment.
Outbound networking configuration for the sandbox. Accepts an object with an 'allowlist' array to restrict traffic, or the string 'disabled' to turn off all network access. Omit entirely to allow all outbound traffic with no header injection.
#### Possible Types
object Outbound networking configuration for the sandbox. When specified, restricts which external domains the sandbox can reach. Omit entirely to allow all outbound traffic with no header injection.
allowlist array (AllowlistEntry) (optional) List of allowed outbound domains. Only requests to listed domains are permitted. Use \[{'domain': '\*'}\] to allow all domains while still injecting headers on specific ones.
A single domain allowlist rule with optional header injection.
#### Fields
domain string (optional) Domain to allow outbound requests to. Supports wildcards (e.g. '\*.googleapis.com'). Use '\*' to allow all domains.
transform array (object) or object (optional) Headers to inject on all outbound requests matching this domain. Accepts a single dict or a list of dicts. The egress proxy injects these automatically.
string Turns all network off.
#### Possible values
- `disabled`
Turns all network off.
size_bytes string (optional) Output only. The total size of the environment files in bytes, output only.
sources array (Source) (optional) Sources to be mounted into the environment.
A source to be mounted into the environment.
#### Fields
content string (optional) The inline content if \`type\` is \`INLINE\`.
encoding string (optional) Optional encoding for inline content (e.g. \`base64\`).
source string (optional) The source of the environment.
For GCS, this is the GCS path.
For GitHub, this is the GitHub path.
target string (optional) Where the source should appear in the environment.
type enum (string) (optional) No description provided.
Possible
values:
- `gcs`
A GCS bucket.
- `inline`
Inline content.
- `repository`
A generic repository. The protocol prefix in the source URL
identifies the provider (e.g., github://, gcs://).
- `skill_registry`
A skill resource from the Skill Registry Service.
Skill: projects/{project}/locations/{location}/skills/{skill}
SkillRevision:
projects/{project}/locations/{location}/skills/{skill}/revisions/{revision}
Support mounting all skills under a project:
projects/{project}/locations/{location}/skills.
status enum (string) (optional) Output only. The status of the environment container.
Possible
values:
- `active`
Output only. The status of the environment container.
- `expired`
Output only. The status of the environment container.
updated string (optional) Output only. The time at which the environment was last updated in ISO 8601 format
(YYYY-MM-DDThh:mm:ssZ).