> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Graph Overview

> Build programmable, multi-turn AI conversation sessions with Connectly agents — init, invoke, and close sessions entirely in code 🧑‍💻

The Agent Graph API lets you build multi-turn AI-powered conversations with Connectly agents entirely in code. You control the full session lifecycle — starting a session, passing customer input, receiving AI responses, and closing the session when the conversation ends.

## Use cases

<CardGroup cols={3}>
  <Card title="Custom chatbots" icon="robot">
    Embed a Connectly AI agent in your own web or mobile interface.
  </Card>

  <Card title="Sales assistants" icon="bag-shopping">
    Guide customers through product discovery and purchase flows programmatically.
  </Card>

  <Card title="Support automation" icon="headset">
    Resolve common queries without human escalation, integrated into your existing systems.
  </Card>
</CardGroup>

***

## Session lifecycle

Every Agent Graph interaction follows a three-phase lifecycle:

<Steps>
  <Step title="Init">
    Call [POST /agent\_graph/init](https://docs.connectly.ai/api-reference/agent-graph-init) with your `businessId` and `clientKey`. Receive a `sessionId` that identifies this conversation.
  </Step>

  <Step title="Invoke">
    Call [POST /agent\_graph/invoke](https://docs.connectly.ai/api-reference/agent-graph-invoke) (or `/invoke_sync`) with the `sessionId` and customer `inputEvents`. Receive the agent's response. Repeat for each turn in the conversation.
  </Step>

  <Step title="Close">
    Call [POST /agent\_graph/close](https://docs.connectly.ai/api-reference/agent-graph-close) when the conversation is complete to release the session and its resources.
  </Step>
</Steps>

***

## Endpoints

| Method | Endpoint                                  | Description                                            |
| ------ | ----------------------------------------- | ------------------------------------------------------ |
| `POST` | `/external/v1/ai/agent_graph/init`        | Start a session — returns `sessionId`.                 |
| `POST` | `/external/v1/ai/agent_graph/invoke`      | Send input, receive a streaming NDJSON response.       |
| `POST` | `/external/v1/ai/agent_graph/invoke_sync` | Send input, receive a single aggregated JSON response. |
| `POST` | `/external/v1/ai/agent_graph/close`       | End a session and release its resources.               |
| `POST` | `/external/v1/ai/agent_graph/health`      | Check API availability.                                |

All endpoints are hosted at `https://api.connectly.ai`.

***

## Authentication

Include your API key in the `x-api-key` header (lowercase):

```text theme={null}
x-api-key: YOUR_API_KEY
```

***

## Required fields

All endpoints (except `/init`) require these three fields in the request body:

| Field        | Description                                                                   |
| ------------ | ----------------------------------------------------------------------------- |
| `businessId` | Your Connectly business UUID.                                                 |
| `clientKey`  | A stable identifier for the customer (e.g. phone number or internal user ID). |
| `sessionId`  | The session ID returned by `/init`.                                           |

***

## Streaming vs sync

The `/invoke` endpoint returns a streaming NDJSON response — one JSON object per line — so your application can begin processing the agent's reply progressively rather than waiting for the full response.

Use `/invoke_sync` when you don't need streaming — for example, in a backend job that waits for the complete response before proceeding. It returns a single aggregated JSON object and works with a standard `response.json()` call.

<Tip>
  Never call `response.json()` on a streaming `/invoke` response — it will throw a parse error. See [NDJSON streaming](https://docs.connectly.ai/ai/parsing-ndjson) for the correct approach.
</Tip>

***

## End-to-end example (Python)

```python theme={null}
import requests, json

BASE_URL = "https://api.connectly.ai/external/v1/ai/agent_graph"
HEADERS  = {"Content-Type": "application/json", "x-api-key": "YOUR_API_KEY"}
BUSINESS_ID = "YOUR_BUSINESS_ID"
CLIENT_KEY  = "YOUR_CLIENT_KEY"

# 1. Init
session_id = requests.post(f"{BASE_URL}/init", headers=HEADERS,
    json={"businessId": BUSINESS_ID, "clientKey": CLIENT_KEY}
).json()["response"]["sessionId"]

# 2. Invoke (streaming)
response = requests.post(f"{BASE_URL}/invoke", headers=HEADERS,
    json={
        "businessId": BUSINESS_ID,
        "clientKey": CLIENT_KEY,
        "sessionId": session_id,
        "inputEvents": [{
            "messageEvent": {
                "role": "USER",
                "content": {"textContent": {"text": "What are your store hours?"}}
            }
        }]
    },
    stream=True
)
for raw_line in response.iter_lines():
    if raw_line:
        print(json.loads(raw_line.decode("utf-8")))

# 3. Close
requests.post(f"{BASE_URL}/close", headers=HEADERS,
    json={"businessId": BUSINESS_ID, "clientKey": CLIENT_KEY, "sessionId": session_id})
```

***

## Next steps

<CardGroup cols={2}>
  <Card title="Init session" icon="play" href="https://docs.connectly.ai/api-reference/agent-graph-init">
    Start a conversation and get a `sessionId`.
  </Card>

  <Card title="Invoke (stream)" icon="bolt" href="https://docs.connectly.ai/api-reference/agent-graph-invoke">
    Send input events and parse the NDJSON streaming response.
  </Card>

  <Card title="Invoke (sync)" icon="arrow-right-arrow-left" href="https://docs.connectly.ai/api-reference/agent-graph-invoke-sync">
    Get a single aggregated response without streaming.
  </Card>

  <Card title="NDJSON streaming" icon="code" href="https://docs.connectly.ai/ai/parsing-ndjson">
    How to correctly parse the streaming response body.
  </Card>
</CardGroup>