Agents & Context Graphs
Define agent personas and versioned context graphs (state machines) that power conversation flows.
Manage the core agent definitions and context graphs that power your organization's AI services. Agents define the persona and behavior of your AI; context graphs define the conversational flow and state management.
How Agents and Context Graphs Relate to Services
Agents and context graphs are the building blocks of services. A service combines:
An Agent (persona, identity, behaviors, communication style)
A Context Graph (the state machine that defines conversational flow)
Version Sets that pin specific versions of each for deployment
Both agents and context graphs are versioned. You create the resource first, then create versions of it. Services reference specific versions through version sets.
Agent Management
Create an Agent
Create a new agent definition for the organization. This creates the agent container. You must then create at least one version before the agent can be used in a service.
Permission required: Organization:CreateAgent
Create a new agent for the given organization. No default version for the agent will be created, so one must later to create a version for this agent so it can be used in a service.
Permissions
This endpoint requires the following permissions:
Organization:CreateAgentfor the new agent.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]The name of the new agent.
Succeeded.
The ID of the newly created agent.
Invalid authorization credentials.
Missing required permissions.
The specified organization does not exist.
An Agent with the same name already exists.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/organization/agent HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 21
{
"agent_name": "text"
}{
"id": "text"
}List Agents
Retrieve agents for the organization. Supports filtering by deprecation status and ID.
Permission required: Organization:GetAgent (only agents the caller has permission for are returned)
Query parameters:
deprecated: filter by deprecation statusid: filter by specific agent IDs (repeatable)limit: results per page (integer)continuation_token: pagination token (integer)
Return a list of agents for the organization.
Permissions
This endpoint may be impacted by the following permissions:
- Only agents that the authenticated user has the
Organization:GetAgentpermission on will be returned.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
Whether the agent is deprecated.
The IDs of the agents to filter for.
[]The maximum number of agents to return.
10The continuation token from the previous request used to retrieve the next page of agents.
0The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]Succeeded.
Whether there are more agents to retrieve.
A token to supply to the next request to retrieve the next page of agents. Only populated if has_more is True.
Invalid authorization credentials.
Missing required permissions.
The specified organization does not exist.
Invalid request path parameter or query parameter failed validation.
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
The service is going through temporary maintenance.
GET /v1/{organization}/organization/agent HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
{
"agents": [
{
"id": "text",
"name": "text",
"deprecated": true,
"latest_version": 1
}
],
"has_more": true,
"continuation_token": 1
}Create an Agent Version
Create a new version of an agent. For the first version, all fields must be provided. For later versions, only supply the fields you want to change. Other fields carry forward from the previous latest version.
Permission required: Organization:CreateAgentVersion
Fields that can be set per version:
initials
The agent's display initials
identity
Information about the agent's identity
background
A description of the agent's background
behaviors
Behavioral guidelines the agent follows
communication_patterns
Descriptions of the agent's communication style
voice_config
Voice configuration (set to null to leave unchanged)
Create a new version of the given agent. If there's no existing versions, all fields in the request must be filled and they will be used to create the initial version of the agent. Otherwise, only fill the fields that need to be updated, and the new version will retain other fields from the previous latest version.
Permissions
This endpoint requires the following permissions:
Organization:CreateAgentVersionfor the new version of the agent.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The ID of the agent to create a new version for.
^[a-f0-9]{24}$The version number of the new agent version. If specified, this endpoint throws an error if the next version of the agent in the database doesn't equal to the value of this parameter.
The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]The agent's initials.
A description of the agent's background.
A list of behavioral guidelines that this agent follows.
A list of descriptions that illustrate the communication styles of this agent.
Succeeded.
Numerical version ID that describes how many iterations of this agent occurred before this version. Note that this is for reference only.
Any identification of an agent version in Amigo APIs use the id field.
For initial version of an agent, this field will be 1.
The time at which this version was created.
Attempt to create the initial version for an agent, but not all fields in the request object are defined. Or, the specified voice ID doesn't exist.
Invalid authorization credentials.
Missing required permissions.
The specified organization or agent does not exist.
The specified version is not the expected next version for the agent.
Invalid request path parameter, request body, or request query parameter failed validation.
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/organization/agent/{agent_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 348
{
"initials": "text",
"identity": {
"name": "text",
"role": "text",
"developed_by": "text",
"default_spoken_language": "aaa",
"relationship_to_developer": {
"ownership": "text",
"type": "text",
"conversation_visibility": "text",
"thought_visibility": "text"
}
},
"background": "text",
"behaviors": [
"text"
],
"communication_patterns": [
"text"
],
"voice_config": {
"voice_id": "text"
}
}{
"version": 1,
"created_at": "2026-01-01T00:00:00.000Z"
}Delete an Agent
Mark an agent as deprecated. The agent and its versions are not physically deleted, but new services cannot use this agent and inactive services cannot be activated with it.
Permission required: Organization:DeleteAgent
Delete the specified agent from the organization. In practice, this endpoint marks the agent as deprecated, but will not delete this agent nor any of its versions. It does prevent new services (or inactive services to be activated) from using this agent.
An error will be raised if this endpoint is called when an active service still utilizes this agent. However, any ongoing conversation using this agent will continue to work.
Permissions:
Organization:DeleteAgentfor the agent to delete.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The ID of the agent to delete
^[a-f0-9]{24}$The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]Succeeded.
An active service exists that utilizes this agent.
Invalid authorization credentials.
Missing required permissions.
The specified organization or agent does not exist.
The specified agent is already deleted
Invalid request path parameter failed validation.
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
The service is going through temporary maintenance.
DELETE /v1/{organization}/organization/agent/{agent_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
No content
Get Agent Versions
Retrieve the version history of an agent.
Permission required: Organization:GetAgent
Query parameters:
version: filter by specific version numberlimit: results per page (integer)continuation_token: pagination token (integer)sort_by: sort order (repeatable)
Retrieve the versions of an agent.
Permissions
This endpoint requires the following permissions:
Organization:GetAgentfor the agent to retrieve.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The ID of the agent.
^[a-f0-9]{24}$The versions of the agent to retrieve. One can specify an exact version to retrieve, which is either the version number or latest, which retrieves the latest version. Alternatively, one can specify a range of inclusive lower and upper bound for the version number separated by -, and every version within the range would be retrieved.
1The maximum number of agent versions to return.
10The continuation token from the previous request used to retrieve the next page of agent version.
0The fields to sort the versions by. Supported fields are version. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.
[]The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]Succeeded.
Whether there are more agent versions to retrieve.
A token to supply to the next request to retrieve the next page of agent versions. Only populated if has_more is True.
Invalid authorization credentials.
Missing required permissions.
Specified organization or agent is not found.
Invalid request path parameter or request query parameter failed validation.
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
The service is going through temporary maintenance.
GET /v1/{organization}/organization/agent/{agent_id}/version HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
{
"agent_versions": [
{
"org_id": "text",
"agent_id": "text",
"version": 1,
"voice_config": {
"voice_id": "text",
"stability": 0,
"similarity_boost": 0,
"style": 0
},
"initials": "text",
"identity": {
"name": "text",
"role": "text",
"developed_by": "text",
"default_spoken_language": "text",
"relationship_to_developer": {
"ownership": "text",
"type": "text",
"conversation_visibility": "text",
"thought_visibility": "text"
}
},
"background": "text",
"behaviors": [
"text"
],
"communication_patterns": [
"text"
],
"created_at": "2026-01-01T00:00:00.000Z",
"creator": {
"org_id": "text",
"user_id": "text"
}
}
],
"has_more": true,
"continuation_token": 1
}Context Graph Management
Create a Context Graph
Create a new context graph for the organization. This creates the container. You must then create at least one version before it can be used in a service.
Permission required: Organization:CreateServiceHierarchicalStateMachine
Create a service hierarchical state machine
Create a new state machine for the given organization. No default version for the state machine will be created, so one must later create a version for this state machine so it can be used in a service.
Permissions
This endpoint requires the following permissions:
Organization:CreateServiceHierarchicalStateMachinefor the new service hierarchical state machine.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]The name of the new state machine.
Succeeded.
The ID of the newly created state machine.
Invalid authorization credentials.
Missing required permissions.
The specified organization does not exist.
A state machine with the same name already exists.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/organization/service_hierarchical_state_machine HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 29
{
"state_machine_name": "text"
}{
"id": "text"
}List Context Graphs
Retrieve context graphs for the organization. Supports filtering by deprecation status and ID.
Permission required: Organization:GetServiceHierarchicalStateMachine (only context graphs the caller has permission for are returned)
Query parameters:
deprecated: filter by deprecation statusid: filter by specific IDs (repeatable)limit: results per page (integer)continuation_token: pagination token (integer)
Get service hierarchical state machines for an organization
Return a list of service hierarchical state machines for the organization.
Permissions
This endpoint may be impacted by the following permissions:
- Only state machines that the authenticated user has the
Organization:GetServiceHierarchicalStateMachinepermission on will be returned.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
Whether the state machine is deprecated.
The IDs of the state machines to filter for.
[]The maximum number of service hierarchical state machines to return.
50The continuation token from the previous request used to retrieve the next page of state machines.
0The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]Succeeded.
Whether there are more state machines to fetch.
A token to supply to the next request to retrieve the next page of state machines. Only populated if has_more is True.
Invalid authorization credentials.
Missing required permissions.
The specified organization does not exist.
Invalid request path parameter or query parameter failed validation.
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
The service is going through temporary maintenance.
GET /v1/{organization}/organization/service_hierarchical_state_machine HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
{
"service_hierarchical_state_machines": [
{
"id": "text",
"name": "text",
"deprecated": true,
"latest_version": 1
}
],
"has_more": true,
"continuation_token": 1
}Create a Context Graph Version
Create a new version of a context graph. The version defines the full state machine including states, transitions, initial states, terminal states, and behavioral guidelines.
Permission required: Organization:CreateServiceHierarchicalStateMachineVersion
The version must satisfy these constraints:
Each action state must have at least one action
Exit condition
next_statevalues must reference existing states (not the current state), or reference external state machinesRequired fields include
description,states,new_user_initial_state,returning_user_initial_state,terminal_state,references, and global guidelines
description
A description of this context graph version
states
The internal states in the context graph
new_user_initial_state
The starting state for new users (must be an action state)
returning_user_initial_state
The starting state for returning users (must be an action state)
terminal_state
The state when a session ends (must be an action state)
references
Dictionary of external context graphs this one references
global_intra_state_navigation_guidelines
Guidelines for navigating between subgoals and exit conditions
global_action_guidelines
Guidelines for agent behavior when engaging with users
global_boundary_constraints
Guidelines for what the agent should not do
Create a service hierarchical state machine version
Create a new version for the given service hierarchical state machine. The new version will be created with the supplied data. It needs to satisfy the following constraints:
- Each action state must have at least one action.
- For action and decision states, each exit condition's
next_statemust either be a string that exists in the states and cannot be the same as the current state, or a 2-tuple of strings, with the first string of the form{external_service_hierarchical_state_machine_reference.external_state_name}, and the second string the jumpback state which must be a state in the states. - For
recall,reflection, andtool_callstates,next_statemust either be a string that exists in the states and cannot be the same as the current state, or a 2-tuple of strings, with the first string of the form{external_service_hierarchical_state_machine_reference.external_state_name}, and the second string the jumpback state which must be a state in the states. - The terminal state cannot have exit conditions and must have exactly one action.
See the per-request-field documentation for more field-specific constraints.
Due to the complexity of the state machine data structure, this endpoint provides a dry_run parameter. If set to True, the endpoint will check the supplied state machine would pass validations,
but does not actually create a new version. In this case, the endpoint returns an empty response with a 201 status code.
Permissions:
This endpoint requires the following permissions:
Organization:CreateServiceHierarchicalStateMachineVersionfor the service hierarchical state machine.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The ID of the service hierarchical state machine to create a new version for.
^[a-f0-9]{24}$The version number of the new state machine version. If specified, this endpoint throws an error if the next version of the state machine in the database doesn't equal to the value of this parameter.
Whether to perform a dry run of the operation.
falseThe Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]A description of the service hierarchical state machine.
The state a new user will be in when a session starts. This must be an action state, and must be an internal state.
^[A-Za-z0-9_]+$The state a returning user will be in when a session starts. This must be an action state, and must be an internal state.
^[A-Za-z0-9_]+$The state the user will be in when the session ends. This must be an action state, and must be an internal state.
^[A-Za-z0-9_]+$A list of guidelines for how the agent will navigate between subgoals and exit conditions within this state. This is injected into the intra_state_navigation_guidelines field of every action state.
A list of guidelines for how the agent will behave when engaging with user. This is injected into the action_guidelines field of every action state.
A list of guidelines for how the agent will not behave when engaging with user. This is injected into the boundary_constraints field of every action state.
Succeeded.
Numerical version ID that describes how many iterations of this service hierarchical state machine occurred before this version. Note that this is for reference only.
Any identification of a service hierarchical state machine version in Amigo APIs use the id field.
For the initial version of a service hierarchical state machine, this field will be 1.
The time at which this version was created.
The specified state machine version depends on another state machine that either doesn't exist or is deprecated
Invalid authorization credentials.
Missing required permissions.
The specified organization, state machine, or tool does not exist.
The specified version number is not the expected next version for the state machine.
Invalid request path parameter, request body, or request query parameter failed validation.
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/organization/service_hierarchical_state_machine/{service_hierarchical_state_machine_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 973
{
"description": "text",
"states": [
{
"type": "text",
"name": "text",
"objective": "text",
"actions": [
"text"
],
"intra_state_navigation_guidelines": [
"text"
],
"action_guidelines": [
"text"
],
"boundary_constraints": [
"text"
],
"exit_conditions": [
{
"description": "text",
"next_state": "text"
}
],
"action_tool_call_specs": [
{
"tool_id": "text",
"version_constraint": "text",
"additional_instruction": "text",
"audio_fillers": [
"text"
],
"audio_filler_triggered_after": 1,
"result_persistence": "ephemeral"
}
],
"exit_condition_tool_call_specs": [
{
"tool_id": "text",
"version_constraint": "text",
"additional_instruction": "text",
"audio_fillers": [
"text"
],
"audio_filler_triggered_after": 1,
"result_persistence": "ephemeral"
}
],
"skip_active_memory_retrieval": true
}
],
"new_user_initial_state": "text",
"returning_user_initial_state": "text",
"terminal_state": "text",
"references": {
"ANY_ADDITIONAL_PROPERTY": []
},
"global_intra_state_navigation_guidelines": [
"text"
],
"global_action_guidelines": [
"text"
],
"global_boundary_constraints": [
"text"
]
}{
"version": 1,
"created_at": "2026-01-01T00:00:00.000Z"
}Delete a Context Graph
Mark a context graph as deprecated. The context graph and its versions are not physically deleted, but new services cannot use it and inactive services cannot be activated with it.
Permission required: Organization:DeleteServiceHierarchicalStateMachine
Delete a service hierarchical state machine
Delete the specified state machine from the organization. In practice, this endpoint marks the state machine as deprecated, but will not delete this state machine nor any of its versions. It does prevent new services (or inactive services to be activated) from using this state machine.
An error will be raised if this endpoint is called when an active service still utilizes this state machine. However, any ongoing conversation using this state machine, as well as any state machine version that depends on this state machine will continue to work.
Permissions:
Organization:DeleteServiceHierarchicalStateMachinefor the state machine to delete.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The ID of the state machine to delete
^[a-f0-9]{24}$The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]Succeeded.
An active service exists that utilizes this state machine.
Invalid authorization credentials.
Missing required permissions.
The specified organization or state machine does not exist.
The specified state machine is already deleted
Invalid request path parameter failed validation.
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
The service is going through temporary maintenance.
DELETE /v1/{organization}/organization/service_hierarchical_state_machine/{state_machine_id}/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
No content
Get Context Graph Versions
Retrieve the version history of a context graph.
Permission required: Organization:GetServiceHierarchicalStateMachine
Query parameters:
version: filter by specific version numberlimit: results per page (integer)continuation_token: pagination token (integer)sort_by: sort order (repeatable)
Get service hierarchical state machine versions
Retrieve the versions of a state machine.
Permissions
This endpoint requires the following permissions:
Organization:GetServiceHierarchicalStateMachinefor the state machine to retrieve.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.
The ID of the state machine.
^[a-f0-9]{24}$The versions of the state machine to retrieve. One can specify an exact version to retrieve, which is either the version number or latest, which retrieves the latest version. Alternatively, one can specify a range of inclusive lower and upper bound for the version number separated by -, and every version within the range would be retrieved.
1The maximum number of state machine versions to return.
10The continuation token from the previous request used to retrieve the next page of state machine versions.
0The fields to sort the versions by. Supported fields are version. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.
[]The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.
[]Succeeded.
Whether there are more state machine versions to retrieve.
A token to supply to the next request to retrieve the next page of state machine versions. Only populated if has_more is True.
Invalid authorization credentials.
Missing required permissions.
Specified organization or service hierarchical state machine is not found.
Invalid request path parameter or request query parameter failed validation.
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
The service is going through temporary maintenance.
GET /v1/{organization}/organization/service_hierarchical_state_machine/{service_hierarchical_state_machine_id}/version HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
{
"state_machine_versions": [
{
"org_id": "text",
"service_hierarchical_state_machine_id": "text",
"version": 1,
"created_at": "2026-01-01T00:00:00.000Z",
"creator": {
"org_id": "text",
"user_id": "text"
},
"description": "text",
"states": [
{
"type": "text",
"name": "text",
"objective": "text",
"actions": [
"text"
],
"intra_state_navigation_guidelines": [
"text"
],
"action_guidelines": [
"text"
],
"boundary_constraints": [
"text"
],
"exit_conditions": [
{
"description": "text",
"next_state": "text"
}
],
"action_tool_call_specs": [
{
"tool_id": "text",
"version_constraint": "text",
"additional_instruction": "text",
"audio_fillers": [
"text"
],
"audio_filler_triggered_after": 1,
"result_persistence": "ephemeral"
}
],
"exit_condition_tool_call_specs": [
{
"tool_id": "text",
"version_constraint": "text",
"additional_instruction": "text",
"audio_fillers": [
"text"
],
"audio_filler_triggered_after": 1,
"result_persistence": "ephemeral"
}
],
"skip_active_memory_retrieval": true
}
],
"new_user_initial_state": "text",
"returning_user_initial_state": "text",
"terminal_state": "text",
"references": {
"ANY_ADDITIONAL_PROPERTY": []
},
"global_intra_state_navigation_guidelines": [
"text"
],
"global_action_guidelines": [
"text"
],
"global_boundary_constraints": [
"text"
]
}
],
"has_more": true,
"continuation_token": 1
}Typical Workflow
Create the agent and context graph containers
Create initial versions of each with full configuration
Create a service referencing the agent and context graph
Configure version sets (release, staging, dev) to pin specific versions
Iterate by creating new versions and updating version sets
Related
Classic API -> Organization Management
Classic API -> Services
Classic API -> Tools
Best Practices → Version Sets & Promotion
Last updated
Was this helpful?