# Services

## Understanding Amigo Services

{% hint style="info" %}
**Service Types**

Your integration may include multiple service types, each designed for specific interaction scenarios:

* **Meet & Greet**: optimized for new user onboarding
* **Adaptive Support**: designed for returning user support

Each service has a unique service ID that you reference when creating conversations. Services are configured with Context Graphs (the API may call these "state machines") that define how agents navigate problem spaces. Learn more about Context Graphs in our [Conceptual Documentation](https://docs.amigo.ai/agent/context-graphs). For enterprise voice and EHR workflows, see [Platform API: Services](/developer-guide/platform-api/platform-api/services.md).
{% endhint %}

Services can be connected in a workflow (for example, Meet & Greet leading to Adaptive Support), but you still start each conversation with the correct service ID so the user lands in the right experience.

### Service Routing Flow

{% @mermaid/diagram content="%%{init: {"flowchart": {"useMaxWidth": true, "nodeSpacing": 30, "rankSpacing": 40}, "theme": "base", "themeVariables": {"primaryColor": "#D4E2E7", "primaryTextColor": "#100F0F", "primaryBorderColor": "#083241", "lineColor": "#575452", "textColor": "#100F0F", "clusterBkg": "#F1EAE7", "clusterBorder": "#D7D2D0"}}}%%
flowchart TB
Start(\[User Arrives]) --> Check{Has account?}
Check -->|No| MeetGreet\[Meet & Greet Service]
Check -->|Yes| Returning{Returning user?}

```
MeetGreet -->|completes onboarding| Onboard[User Onboarded]
Onboard --> Adaptive[Adaptive Support Service]

Returning -->|Yes| Adaptive
Returning -->|No| MeetGreet

Adaptive --> Interaction[User Interaction]
Interaction --> Return{User returns later?}
Return -->|Yes| Adaptive

style MeetGreet fill:#DDE3DB,stroke:#2c3827,color:#100F0F,stroke-width:2px
style Adaptive fill:#F0DDD9,stroke:#AA412A,color:#100F0F,stroke-width:2px
style Start fill:#D4E2E7,stroke:#083241,color:#100F0F,stroke-width:2px
style Onboard fill:#E8E2EB,stroke:#C5BACE,color:#100F0F,stroke-width:2px" %}
```

## Retrieving Available Services

To discover all available services for your organization:

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/service/?limit=10&is_active=true' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'Accept: application/json'
```

{% endtab %}

{% tab title="Python SDK" %}

```python
from amigo_sdk import AmigoClient
from amigo_sdk.models import GetServicesParametersQuery

with AmigoClient() as client:
    services = client.services.get_services(
        GetServicesParametersQuery(limit=10, is_active=True)
    )

    for service in services.services:
        print(f"Service: {service.name} (ID: {service.id})")
```

*Note: Async version also available with `async with AsyncAmigoClient()`*
{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
import { AmigoClient } from "@amigo-ai/sdk";

const client = new AmigoClient({ ...config });
const services = await client.services.getServices({
  limit: 10,
  is_active: true,
});

services.services?.forEach((service) => {
  console.log(`Service: ${service.name} (ID: ${service.id})`);
});
```

{% endtab %}
{% endtabs %}

The response will contain a list of services with their respective IDs, names, and other metadata.

```json
{
  "services": [
    {
      "id": "6618791275130b73714e8d1c",
      "name": "Meet & Greet",
      "description": "A service that handles a scenario",
      "icon": null,
      "active_conversation_id": null,
      "is_active": true,
      "service_hierarchical_state_machine_id": "6618791375530b73714e8d1a",
      "agent_id": "6618791275530b73714e9d18",
      "conversation_metrics": []
    }
  ]
}
```

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/service/" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Create a Service

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/service/' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "service_hierarchical_state_machine_id": "8b5c6599bfb8ffc45646b289",
  "agent_id": "0d0b781189c14189526c2603",
  "name": "New Service",
  "description": "A description",
  "is_active": true
}'
```

{% endtab %}

{% tab title="Python SDK" %}

```python
from amigo_sdk import AmigoClient
from amigo_sdk.generated.model import ServiceCreateServiceRequest

with AmigoClient() as client:
    result = client.services.create_service(
        ServiceCreateServiceRequest(
            service_hierarchical_state_machine_id="8b5c6599bfb8ffc45646b289",
            agent_id="0d0b781189c14189526c2603",
            name="New Service",
            description="A description",
            is_active=True,
        )
    )
    print(f"Created service: {result.id}")
```

*Note: Async version also available with `async with AsyncAmigoClient()`*
{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
import { AmigoClient, serviceId } from "@amigo-ai/sdk";

const client = new AmigoClient({ ...config });
const result = await client.services.createService({
  body: {
    service_hierarchical_state_machine_id: "8b5c6599bfb8ffc45646b289",
    agent_id: "0d0b781189c14189526c2603",
    name: "New Service",
    description: "A description",
    is_active: true,
  },
});
console.log(`Created service: ${result.id}`);
```

{% endtab %}
{% endtabs %}

The response will contain the ID of the created service:

```json
{
  "id": "6618791275130b73714e8d1c"
}
```

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/service/" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Update a Service

To update a service's non-functional metadata, use the following:

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/service/<SERVICE-ID>/' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{"is_active": false}'
```

{% endtab %}

{% tab title="Python SDK" %}

```python
from amigo_sdk import AmigoClient
from amigo_sdk.generated.model import ServiceUpdateServiceRequest

with AmigoClient() as client:
    client.services.update_service(
        service_id="6618791275130b73714e8d1c",
        body=ServiceUpdateServiceRequest(is_active=False),
    )
```

*Note: Async version also available with `async with AsyncAmigoClient()`*
{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
import { AmigoClient, serviceId } from "@amigo-ai/sdk";

const client = new AmigoClient({ ...config });
await client.services.updateService({
  serviceId: serviceId("6618791275130b73714e8d1c"),
  body: { is_active: false },
});
```

{% endtab %}
{% endtabs %}

To change a service's functional fields such as its agent ID, create a new service and delete the old service.

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/service/{service\_id}/" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Service Mapping Best Practices

{% hint style="success" %}
**Effective Service Routing**

For effective service routing in your application:

1. **Service ID Persistence**: store service IDs in your system with descriptive labels.
2. **User Journey Mapping**: map user states to the right services. For example, first-time users go to a Meet & Greet service (service ID: `67a23a08b02fe1e74341a6f8`), and returning users go to a Reactive Support service (service ID: `675769a1d71dbf8cf042271f`).
3. **Dynamic Routing**: implement logic in your application to direct users to the appropriate service based on their status or needs.
   {% endhint %}

## Service Versioning with Version Sets

Services use **version sets** to manage deployments across different environments. Each service can have multiple version sets (for example, `"release"`, `"staging"`, `"dev"`), so you can test and promote changes without modifying the service ID.

### What are Version Sets?

A version set is a named configuration that selects specific versions of:

* **Agent** (agent\_id + version number)
* **Context Graph** (service\_hierarchical\_state\_machine\_id + version number)
* **Dynamic Behaviors** (applied\_behavior\_ids, a list of behavior configurations)
* **LLM Model Preferences** (model configuration for this deployment)

This enables safe, controlled deployment:

```
Service: "Customer Support"
├─ Version Set: "release" → Agent v2.1, Context Graph v3.0, premium-tier model
├─ Version Set: "staging" → Agent v2.2, Context Graph v3.1, standard-tier model
└─ Version Set: "dev" → Agent v3.0, Context Graph v4.0, economy-tier model
```

### Using Version Sets

When creating conversations, specify the version set:

* **`service_version_set_name`**: the version set to use (typically `"release"` for production)
* **`service_id`**: the unique identifier for the service

**Example:**

```json
{
  "service_id": "6618791275130b73714e8d1c",
  "service_version_set_name": "release"
}
```

This approach gives you:

* **Stable production** through the `"release"` version set
* **Safe testing** through `"staging"` or `"dev"` version sets
* **Zero-downtime deployments** by updating version sets without changing service\_id
* **Easy rollback** by reverting version set configurations

For more on managing version sets and promotion workflows, see [Version Sets Best Practices](/developer-guide/operations/devops/version-sets-best-practices.md).

## Dynamic Behaviors

Services can be extended with **Dynamic Behaviors**: configurable rule-based actions that trigger based on conversation context. Unlike agents and context graphs, which define the core conversational flow, dynamic behaviors add conditional responses and actions that can be applied across multiple services.

<details>

<summary>Dynamic Behaviors: key concepts, use cases, and configuration</summary>

#### Key Concepts

**Dynamic Behaviors** are:

* **Reusable**: a single behavior can be applied to multiple services
* **Version-controlled**: each behavior has its own version history
* **Trigger-based**: activate based on specific conversation patterns or conditions
* **Service-agnostic**: can be shared across services with similar needs

#### Common Use Cases

Dynamic behaviors suit scenarios like:

* **Compliance rules**: medical advice disclaimers, safety protocols
* **Escalation triggers**: detecting distress signals and routing to specialists
* **Contextual guidance**: providing domain-specific information (nutrition, exercise, medication)
* **Business logic**: implementing organization-wide policies consistently

#### Integration with Services

Dynamic behaviors are configured at the **version set** level, so you can:

* Test new behaviors in staging without affecting production
* Apply different behavior sets to different deployment environments
* Roll back behavior changes independently of agent or context graph changes

**Example Configuration:**

```
Service: "Health Coach"
├─ Version Set: "release"
│   ├─ Agent: v3
│   ├─ Context Graph: v5
│   └─ Behaviors: [
│       "Medical Support - Emergency Response Protocol",
│       "Diet & Nutrition - Calorie Target Guidance",
│       "Exercise - Safety Screening"
│     ]
└─ Version Set: "staging"
    ├─ Agent: v3
    ├─ Context Graph: v6
    └─ Behaviors: [
        "Medical Support - Emergency Response Protocol",
        "Diet & Nutrition - Calorie Target Guidance",
        "Exercise - Safety Screening",
        "Medication Management - Side Effects Guide" // Testing new behavior
      ]
```

For more details on dynamic behavior tables and queries, see [Dynamic Behaviors Data Access](/developer-guide/classic-api/data-access/organization-tables/dynamic-behaviors.md).

</details>

***

## Get a Specific Version Set

Retrieve details for a specific version set by name.

### Endpoint

```
GET /v1/{org}/service/{service_id}/version_sets/{version_set_name}/
```

### Path Parameters

| Parameter          | Type   | Description                                                     |
| ------------------ | ------ | --------------------------------------------------------------- |
| `org`              | string | Organization identifier                                         |
| `service_id`       | string | Service identifier                                              |
| `version_set_name` | string | Version set name (for example, `release`, `preview`, `staging`) |

### Response

Returns the version set configuration including pinned entity versions.

{% tabs %}
{% tab title="curl" %}

```bash
curl -X GET "https://api.amigo.ai/v1/{org}/service/{service_id}/version_sets/release/" \
  -H "Authorization: Bearer $TOKEN"
```

{% endtab %}

{% tab title="Python" %}

```python
from amigo_sdk import AmigoClient

# Note: get_version_set is not yet in the SDK resource layer.
# Use the HTTP client directly:
with AmigoClient() as client:
    response = client._http.request(
        "GET",
        f"/v1/{client._cfg.organization_id}/service/{service_id}/version_sets/release/"
    )
    import json
    version_set = json.loads(response.text)
    print(f"Agent version: {version_set.get('agent_version')}")
    print(f"Context graph version: {version_set.get('context_graph_version')}")
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
// Note: getVersionSet is not yet in the SDK resource layer.
// Use the underlying fetch client:
const response = await fetch(
  `${baseUrl}/v1/${orgId}/service/${serviceId}/version_sets/release/`,
  { headers: { Authorization: `Bearer ${token}` } }
);
const versionSet = await response.json();
console.log("Agent version:", versionSet.agent_version);
```

{% endtab %}
{% endtabs %}

### Rate Limit

| Method | Rate Limit          |
| ------ | ------------------- |
| GET    | 100 requests/minute |

***

## Upsert a Version Set

Create or update a version set for a service. This is an idempotent operation: if the version set already exists it is updated; otherwise it is created.

### Endpoint

```
PUT /v1/{org}/service/{service_id}/version_sets/{version_set_name}/
```

### Path Parameters

| Parameter          | Type   | Description                                                 |
| ------------------ | ------ | ----------------------------------------------------------- |
| `org`              | string | Organization identifier                                     |
| `service_id`       | string | Service identifier                                          |
| `version_set_name` | string | Version set name (for example, `release`, `staging`, `dev`) |

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request PUT \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/service/<SERVICE-ID>/version_sets/staging/' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
  "agent_id": "0d0b781189c14189526c2603",
  "agent_version": 2,
  "service_hierarchical_state_machine_id": "8b5c6599bfb8ffc45646b289",
  "service_hierarchical_state_machine_version": 3
}'
```

{% endtab %}

{% tab title="Python SDK" %}

```python
from amigo_sdk import AmigoClient
from amigo_sdk.generated.model import ServiceUpsertServiceVersionSetRequest

with AmigoClient() as client:
    client.services.upsert_version_set(
        service_id="6618791275130b73714e8d1c",
        version_set_name="staging",
        body=ServiceUpsertServiceVersionSetRequest(
            agent_id="0d0b781189c14189526c2603",
            agent_version=2,
            service_hierarchical_state_machine_id="8b5c6599bfb8ffc45646b289",
            service_hierarchical_state_machine_version=3,
        ),
    )
```

*Note: Async version also available with `async with AsyncAmigoClient()`*
{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
import { AmigoClient, serviceId } from "@amigo-ai/sdk";

const client = new AmigoClient({ ...config });
await client.services.upsertVersionSet({
  serviceId: serviceId("6618791275130b73714e8d1c"),
  versionSetName: "staging",
  body: {
    agent_id: "0d0b781189c14189526c2603",
    agent_version: 2,
    service_hierarchical_state_machine_id: "8b5c6599bfb8ffc45646b289",
    service_hierarchical_state_machine_version: 3,
  },
});
```

{% endtab %}
{% endtabs %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/service/{service\_id}/version\_sets/{version\_set\_name}/" method="put" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

***

## Delete a Version Set

Remove a version set from a service. This operation cannot be undone.

### Endpoint

```
DELETE /v1/{org}/service/{service_id}/version_sets/{version_set_name}/
```

### Path Parameters

| Parameter          | Type   | Description                |
| ------------------ | ------ | -------------------------- |
| `org`              | string | Organization identifier    |
| `service_id`       | string | Service identifier         |
| `version_set_name` | string | Version set name to delete |

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request DELETE \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/service/<SERVICE-ID>/version_sets/staging/' \
     --header 'Authorization: Bearer <AUTH-TOKEN-OF-USER>'
```

{% endtab %}

{% tab title="Python SDK" %}

```python
from amigo_sdk import AmigoClient

with AmigoClient() as client:
    client.services.delete_version_set(
        service_id="6618791275130b73714e8d1c",
        version_set_name="staging",
    )
```

*Note: Async version also available with `async with AsyncAmigoClient()`*
{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
import { AmigoClient, serviceId } from "@amigo-ai/sdk";

const client = new AmigoClient({ ...config });
await client.services.deleteVersionSet({
  serviceId: serviceId("6618791275130b73714e8d1c"),
  versionSetName: "staging",
});
```

{% endtab %}
{% endtabs %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/service/{service\_id}/version\_sets/{version\_set\_name}/" method="delete" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/developer-guide/classic-api/core-api/services.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.