Tool: save_automation
Validates and converts the generated automation to a Home APIs automation and persists it.
Don't retry if you encounter these errors: PERMISSION_DENIED, UNAUTHENTICATED, OUT_OF_RANGE, RESOURCE_EXHAUSTED, ALREADY_EXISTS. For other errors, retry at most three times.
The following code sample shows how to use curl to call the save_automation MCP tool.
| Curl Request |
|---|
curl --location 'https://home.googleapis.com/mcp' \ --header 'Authorization: Bearer {oauth-access-token}' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "save_automation", "arguments": { // Provide these details according to the MCP tool specification. } }, "jsonrpc": "2.0", "id": 1 }' |
Input Schema
Request to insert or update an automation.
UpsertAutomationRequest
| JSON representation |
|---|
{ "automation": { object ( |
| Fields | |
|---|---|
automation |
Required. The automation to insert or update. For update operation, all fields in the automation will be updated by the specified automation. |
idempotencyKey |
Optional. The idempotency key for the request, preventing duplicate automation creation and update operations. |
Union field
|
|
active |
Optional. Whether the automation should be active or inactive. |
Automation
| JSON representation |
|---|
{ "automationObjectId": string, "structureId": string, "name": string, "description": string, "clientMetadata": { string: string, ... }, "immediateExecution": boolean, "validState": enum ( |
| Fields | |
|---|---|
automationObjectId |
Required. Identifier. If automation_object_id is empty, it will create a new automation. If automation_object_id is provided, it will update the existing automation with the same object id. |
structureId |
Required. The structure the automation belongs to. |
name |
Optional. The name of the automation. If not provided, the system will generate one. If provided, the name should be unique within the structure. |
description |
Optional. The generated description of the automation. |
clientMetadata |
Optional. Metadata of an automation maintained by the clients. An object containing a list of |
immediateExecution |
Optional. If true, the automation will be executed immediately after creation. |
validState |
Output only. The valid state of the automation. |
activeState |
Output only. The active state of the automation. |
runningState |
Output only. The running state of the automation. |
Union field automation. The actual logic behind the automation. automation can be only one of the following: |
|
simpleAutomation |
Optional. Simple automation with starters, conditions and actions. |
Union field
|
|
maxExecutionCount |
Optional. Max execution count of the automation. If unset, the automation can execute an infinite number of times. If set to 0, the automation can execute zero times. |
SimpleAutomation
| JSON representation |
|---|
{ "starters": [ { object ( |
| Fields | |
|---|---|
starters[] |
Required. The starters of the automation. |
conditions[] |
Optional. The conditions of the automation. |
conditionsLogicalOperator |
Optional. The logical operator to connect the conditions. |
actions[] |
Required. The actions of the automation. |
StarterBlock
| JSON representation |
|---|
{ "comparison": { object ( |
| Fields | |
|---|---|
comparison |
Optional. The comparison to compare the starter with the value. |
description |
Optional. The description of the starter. |
starterDuration |
Optional. The duration for which the condition must be satisfied. A duration in seconds with up to nine fractional digits, ending with ' |
Union field starter. The starter to compare. starter can be only one of the following: |
|
homeState |
Optional. The home state to compare. |
homeEvent |
Optional. The home event to compare. |
HomeState
| JSON representation |
|---|
{ "id": string, "type": string, "trait": string } |
| Fields | |
|---|---|
id |
Required. The id of the resource on which to reference the state. |
type |
Required. The general type of the resource on which to execute the action on. |
trait |
Required. The name of the uddm/whdm trait to reference. |
HomeEvent
| JSON representation |
|---|
{ "id": string, "type": string, "event": string, "parameters": { object } } |
| Fields | |
|---|---|
id |
Required. The id of the resource on which to reference the event. |
type |
Required. The general type of the resource on which to execute the action on. |
event |
Required. The name of the uddm/whdm event to reference. |
parameters |
Optional. The parameters for the event, as a struct. |
Struct
| JSON representation |
|---|
{ "fields": { string: value, ... } } |
| Fields | |
|---|---|
fields |
Unordered map of dynamically typed values. An object containing a list of |
FieldsEntry
| JSON representation |
|---|
{ "key": string, "value": value } |
| Fields | |
|---|---|
key |
|
value |
|
Value
| JSON representation |
|---|
{ // Union field |
| Fields | |
|---|---|
Union field kind. The kind of value. kind can be only one of the following: |
|
nullValue |
Represents a JSON |
numberValue |
Represents a JSON number. Must not be |
stringValue |
Represents a JSON string. |
boolValue |
Represents a JSON boolean ( |
structValue |
Represents a JSON object. |
listValue |
Represents a JSON array. |
ListValue
| JSON representation |
|---|
{ "values": [ value ] } |
| Fields | |
|---|---|
values[] |
Repeated field of dynamically typed values. |
Comparison
| JSON representation |
|---|
{ "field": string, "operator": enum ( |
| Fields | |
|---|---|
field |
Required. The field name of the state or event to compare. |
operator |
Required. The operator to compare the state or event with the value. |
operands[] |
Optional. The targets to compare the state or event with. |
Operand
| JSON representation |
|---|
{ // Union field |
| Fields | |
|---|---|
Union field type. The value to compare the state or event with, or the nested comparison to compare the state or event with the nested value. type can be only one of the following: |
|
value |
Optional. The value to compare the state or event with. |
comparison |
Optional. The nested comparison to compare the state or event with the nested value. |
Duration
| JSON representation |
|---|
{ "seconds": string, "nanos": integer } |
| Fields | |
|---|---|
seconds |
Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years |
nanos |
Signed fractions of a second at nanosecond resolution of the span of time. Durations less than one second are represented with a 0 |
ConditionBlock
| JSON representation |
|---|
{ "homeState": { object ( |
| Fields | |
|---|---|
homeState |
Required. The state to compare. |
comparison |
Required. The comparison to compare the state with the value. |
description |
Optional. The description of the condition. |
ActionBlock
| JSON representation |
|---|
{ "description": string, // Union field |
| Fields | |
|---|---|
description |
Optional. The description of the action block. |
Union field action. The action to execute. action can be only one of the following: |
|
homeAction |
Optional. The home action to execute. |
delay |
Optional. The delay to execute the action. |
HomeAction
| JSON representation |
|---|
{ "id": string, "type": string, "command": string, "parameters": { object } } |
| Fields | |
|---|---|
id |
Required. The id of the resource on which to execute the action on. |
type |
Required. The general type of the resource on which to execute the action on. |
command |
Required. The name of the uddm/whdm command to execute. |
parameters |
Optional. The parameters for the action, as a struct. |
Delay
| JSON representation |
|---|
{ "duration": string } |
| Fields | |
|---|---|
duration |
Required. The delay duration in seconds. A duration in seconds with up to nine fractional digits, ending with ' |
ClientMetadataEntry
| JSON representation |
|---|
{ "key": string, "value": string } |
| Fields | |
|---|---|
key |
|
value |
A base64-encoded string. |
NullValue
Represents a JSON null.
NullValue is a sentinel, using an enum with only one value to represent the null value for the Value type union.
A field of type NullValue with any value other than 0 is considered invalid. Most ProtoJSON serializers will emit a Value with a null_value set as a JSON null regardless of the integer value, and so will round trip to a 0 value.
| Enums | |
|---|---|
NULL_VALUE |
Null value. |
ComparisonOperator
The operator to compare the state or event with the value.
| Enums | |
|---|---|
COMPARISON_OPERATOR_UNSPECIFIED |
Unspecified operator. |
EQUALS |
The operator is equals. |
NOT_EQUALS |
The operator is not equals. |
LESS_THAN |
The operator is less than. |
LESS_THAN_EQUALS |
The operator is less than or equals. |
GREATER_THAN |
The operator is greater than. |
GREATER_THAN_EQUALS |
The operator is greater than or equals. |
ANY_MATCH |
The operator is any match. |
BETWEEN |
The operator is between. |
IS_IN |
The operator is is in. |
LogicalOperator
The logical operator to connect the starters.
| Enums | |
|---|---|
LOGICAL_OPERATOR_UNSPECIFIED |
Unspecified logical operator. |
LOGICAL_OPERATOR_AND |
The logical operator is AND. |
LOGICAL_OPERATOR_OR |
The logical operator is OR. |
ValidState
The valid state of the automation.
| Enums | |
|---|---|
VALID_STATE_UNSPECIFIED |
Unspecified valid state. |
VALID |
Automation is valid and can be activated. |
INVALID |
Automation is invalid. |
ActiveState
The active state of the automation.
| Enums | |
|---|---|
ACTIVE_STATE_UNSPECIFIED |
Unspecified active state. |
ACTIVE |
Automation is active. |
INACTIVE |
Automation is inactive. |
RunningState
The running state of the automation.
| Enums | |
|---|---|
RUNNING_STATE_UNSPECIFIED |
Unspecified running state. |
RUNNING |
Automation is running. |
NOT_RUNNING |
Automation is not running. |
Output Schema
Response for UpsertAutomation.
Tool Annotations
Tool annotations are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.
Along with the title string, the following boolean hints are defined as follows:
readOnlyHint: If true, the tool doesn't modify its environment. Default: false.destructiveHint: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.idempotentHint: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.openWorldHint: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.
Destructive Hint: ✅ | Idempotent Hint: ❌ | Read Only Hint: ❌ | Open World Hint: ✅