Managing Journey States via Confident AI SDK

Overview

The Confident AI SDK exposes every State method on the platform. This page documents how to call these methods in all supported languages. See the introduction to install the SDK and set your API key.

Methods

Create State

Adds a state to a journey and returns its id. Send fromStateId and when to connect it from an existing state in the same call; retrieve the journey to read the edge that creates. State names are unique within a journey; reusing one returns a 409.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.journeys.create_state(
    journey_id="<JOURNEY-ID>",
    name="Verify identity",
    instructions="The agent asks for the order number and the email on the account, and checks they match before going further.",
    from_state_id="<JOURNEY-STATE-ID>",
    when="The customer asks for their money back on an order.",
)

For async mode, call a_create_state and await it as shown below:

result = await client.journeys.a_create_state(...)

Parameters

Parameter	Type	Description
`journey_id`	`str`	Required. The id of the journey.
`name`	`str`	Required. The name of the state, unique within the journey.
`instructions`	`str`	Required. What happens at this step of the conversation. When goldens are generated for a path, the instructions of its states, in order, are what the scenario is written from. May be empty.
`from_state_id`	`Optional[str]`	The id of an existing state in this journey to connect the new state from. An edge from that state to the new one is created alongside it, and `when` is then required. Omit it to add an unconnected state.
`when`	`Optional[str]`	The condition for the edge from `fromStateId`, in plain language. Required with `fromStateId` and ignored without it. An empty condition keeps the edge out of the journey's paths until it is given one.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.journeys.createState(
  "<JOURNEY-ID>",
  "Verify identity",
  "The agent asks for the order number and the email on the account, and checks they match before going further.",
  "<JOURNEY-STATE-ID>",
  "The customer asks for their money back on an order.",
);

Parameters

Parameter	Type	Description
`journeyId`	`string`	Required. The id of the journey.
`name`	`string`	Required. The name of the state, unique within the journey.
`instructions`	`string`	Required. What happens at this step of the conversation. When goldens are generated for a path, the instructions of its states, in order, are what the scenario is written from. May be empty.
`fromStateId`	`string`	The id of an existing state in this journey to connect the new state from. An edge from that state to the new one is created alongside it, and `when` is then required. Omit it to add an unconnected state.
`when`	`string`	The condition for the edge from `fromStateId`, in plain language. Required with `fromStateId` and ignored without it. An empty condition keeps the edge out of the journey's paths until it is given one.

Returns

This method returns an object of type JourneyStateRef.

Update State

Renames a state or rewrites its instructions, and returns it. State names are unique within a journey; taking another state's name returns a 409.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.journeys.update_state(
    journey_id="<JOURNEY-ID>",
    state_id="<JOURNEY-STATE-ID>",
    name="Verify identity",
    instructions="The agent asks for the order number and the email on the account, and checks they match before going further.",
)

For async mode, call a_update_state and await it as shown below:

result = await client.journeys.a_update_state(...)

Parameters

Parameter	Type	Description
`journey_id`	`str`	Required. The id of the journey the state belongs to.
`state_id`	`str`	Required. The id of the state.
`name`	`Optional[str]`	The name of the state, unique within the journey. Omit it to keep the current name.
`instructions`	`Optional[str]`	What happens at this step of the conversation. The text replaces the stored one outright, so send the whole of it. Omit it to keep the current instructions.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.journeys.updateState(
  "<JOURNEY-ID>",
  "<JOURNEY-STATE-ID>",
  "Verify identity",
  "The agent asks for the order number and the email on the account, and checks they match before going further.",
);

Parameters

Parameter	Type	Description
`journeyId`	`string`	Required. The id of the journey the state belongs to.
`stateId`	`string`	Required. The id of the state.
`name`	`string`	The name of the state, unique within the journey. Omit it to keep the current name.
`instructions`	`string`	What happens at this step of the conversation. The text replaces the stored one outright, so send the whole of it. Omit it to keep the current instructions.

Returns

This method returns an object of type JourneyState.

Delete State

Permanently deletes a state and its edges, along with every state that could only be reached through it, and returns the ids of all the states removed. Goldens generated for a path through any of them are kept but no longer belong to any path. The root state cannot be deleted; trying returns a 400.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.journeys.delete_state(
    journey_id="<JOURNEY-ID>",
    state_id="<JOURNEY-STATE-ID>",
)

For async mode, call a_delete_state and await it as shown below:

result = await client.journeys.a_delete_state(...)

Parameters

Parameter	Type	Description
`journey_id`	`str`	Required. The id of the journey the state belongs to.
`state_id`	`str`	Required. The id of the state.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.journeys.deleteState(
  "<JOURNEY-ID>",
  "<JOURNEY-STATE-ID>",
);

Parameters

Parameter	Type	Description
`journeyId`	`string`	Required. The id of the journey the state belongs to.
`stateId`	`string`	Required. The id of the state.

Returns

This method returns an object of type DeleteJourneyStateResult.

Types

DeleteJourneyStateResult

The states removed by deleting a state from a journey.

class DeleteJourneyStateResult:
    id: str
    deleted_state_ids: List[str] = Field(alias="deletedStateIds")

idstrRequired

The id of the state you deleted.

Example: "<JOURNEY-STATE-ID>"

deleted_state_idsList[str]Required

Every state removed: the one you deleted, then any state that could only be reached through it.

Example: ["<JOURNEY-STATE-ID>"]

interface DeleteJourneyStateResult {
  id: string;
  deletedStateIds: string[];
}

idstringRequired

The id of the state you deleted.

Example: "<JOURNEY-STATE-ID>"

deletedStateIdsstring[]Required

Every state removed: the one you deleted, then any state that could only be reached through it.

Example: ["<JOURNEY-STATE-ID>"]

JourneyState

One step of a journey: a point the conversation can reach, with instructions for what happens there.

class JourneyState:
    id: str
    name: str
    instructions: str
    golden_count: int = Field(alias="goldenCount")
    created_at: str = Field(alias="createdAt")
    updated_at: str = Field(alias="updatedAt")

idstrRequired

The id of the state, generated by Confident AI.

Example: "<JOURNEY-STATE-ID>"

namestrRequired

The name of the state, unique within the journey.

Example: "Verify identity"

instructionsstrRequired

What happens at this step of the conversation, as golden generation reads it.

Example: "The agent asks for the order number and the email on the account, and checks they match before going further."

golden_countintRequired

The number of goldens generated for a path through this state.

Example: 10

created_atstrRequired

The time the state was created, as an ISO 8601 datetime.

Example: "2025-01-15T10:30:00+00:00"

updated_atstrRequired

The time the state was last changed, as an ISO 8601 datetime.

Example: "2025-01-16T09:12:00+00:00"

interface JourneyState {
  id: string;
  name: string;
  instructions: string;
  goldenCount: number;
  createdAt: string;
  updatedAt: string;
}

idstringRequired

The id of the state, generated by Confident AI.

Example: "<JOURNEY-STATE-ID>"

namestringRequired

The name of the state, unique within the journey.

Example: "Verify identity"

instructionsstringRequired

What happens at this step of the conversation, as golden generation reads it.

Example: "The agent asks for the order number and the email on the account, and checks they match before going further."

goldenCountnumberRequired

The number of goldens generated for a path through this state.

Example: 10

createdAtstringRequired

The time the state was created, as an ISO 8601 datetime.

Example: "2025-01-15T10:30:00+00:00"

updatedAtstringRequired

The time the state was last changed, as an ISO 8601 datetime.

Example: "2025-01-16T09:12:00+00:00"

JourneyStateRef

A reference to a journey state by its id.

class JourneyStateRef:
    id: str

idstrRequired

The id of the state, generated by Confident AI.

Example: "<JOURNEY-STATE-ID>"

interface JourneyStateRef {
  id: string;
}

idstringRequired

The id of the state, generated by Confident AI.

Example: "<JOURNEY-STATE-ID>"

Building a production pipeline?Design a scalable API workflow for evals, datasets, traces, and promptsTalk to an engineer

Last updated on October 25, 2026

Built byConfident AI