# 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 must be referenced when creating conversations. Services are configured with Context Graphs (the API may refer to these as "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](https://docs.amigo.ai/developer-guide/platform-api/platform-api/services).
{% endhint %}

Though services may be connected in a workflow (e.g., Meet & Greet leading to Adaptive Support), you must initiate conversations with the correct service ID to ensure proper user 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**: Create logical mappings between user states and appropriate services:
   * First-time users → Meet & Greet service (e.g. service ID: `67a23a08b02fe1e74341a6f8`)
   * Returning users → Reactive Support service (e.g. 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 (e.g., `"release"`, `"staging"`, `"dev"`), allowing you to 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 - list of behavior configurations)
* **LLM Model Preferences** (model configuration for this deployment)

This lets you do 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 ensures:

* **Stable production** via the `"release"` version set
* **Safe testing** via `"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](https://docs.amigo.ai/developer-guide/operations/devops/version-sets-best-practices).

## Dynamic Behaviors

Services can be enhanced with **Dynamic Behaviors** - configurable rule-based actions that trigger based on conversation context. Unlike agents and context graphs that 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 are ideal for:

* **Compliance rules**: Ensuring 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, allowing you to:

* Test new behaviors in staging without affecting production
* Apply different behavior sets to different deployment environments
* Roll back behavior changes independently of agent/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](https://docs.amigo.ai/developer-guide/classic-api/data-access/organization-tables/dynamic-behaviors).

</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 (e.g., `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 will be updated, otherwise it will be 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 (e.g., `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 %}