Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway at /v1/agent/*. The ai.enabled feature gate must be active for the tenant.

LangGraph Agent API

AI agent orchestration using LangGraph for multi-step workflows, contextual conversations, and human-in-the-loop approval processes.

Overview

Attribute	Value
Base Path	/api/v1/agent
Authentication	Bearer Token
Feature Gate	ai.enabled must be true
Proxy	Go gateway forwards all /v1/agent/* requests to Python Analytics service at /api/agent/*

The Go API gateway proxies all requests under /v1/agent/* to the Python Analytics service. The Python service requires LangGraph to be installed; endpoints return 503 if the dependency is unavailable.

Agent Chat

Send Message

Process a message through the LangGraph workflow engine. Routes the message through intent classification, RAG retrieval, planning, execution, and optional human approval.

POST /api/v1/agent/chat

Request Body

{
  "message": "What's our current inventory of ribeye?",
  "tenant_id": "restaurant-1",
  "user_id": "user_123",
  "session_id": "sess_abc",
  "shell_type": "staff",
  "domain": "inventory",
  "complexity": 3
}

Field	Type	Required	Description
message	string	Yes	User message to process
tenant_id	string	Yes	Tenant identifier
user_id	string	Yes	User identifier
session_id	string	Yes	Session identifier (used as LangGraph thread ID)
shell_type	string	Yes	Shell context: staff, admin, cockpit, customer
domain	string	No	Domain hint for routing (e.g., inventory, sales, labor, general)
complexity	integer	No	Complexity hint (1-10, default: 3)

Response

{
  "response": "Based on your inventory records, you currently have 45 ribeye steaks in stock...",
  "requires_approval": false,
  "approval_reason": null,
  "session_id": "sess_abc",
  "thread_id": "sess_abc"
}

Field	Type	Description
response	string	Agent's response text (from the last LangChain message)
requires_approval	boolean	Whether the workflow is paused waiting for human approval
approval_reason	string	Reason approval is needed (null if not paused)
session_id	string	Session identifier
thread_id	string	LangGraph thread identifier (same as session_id)

When requires_approval is true, the workflow is paused at the human_approval node. Use the /approve endpoint to resume.

---

Phone Agent Chat

Optimized endpoint for phone/voice interactions. Uses a specialized phone agent graph designed for low latency and concise responses.

POST /api/v1/agent/chat/phone

Request Body

{
  "message": "I'd like to make a reservation for 4 people",
  "tenant_id": "restaurant-1",
  "user_id": "caller_001",
  "session_id": "phone_sess_001",
  "shell_type": "customer"
}

The request body uses the same ChatRequest model as /chat. The shell_type is overridden to "customer" internally for phone callers.

Response

{
  "response": "I'd be happy to help you make a reservation for 4 people. What date and time works best for you?",
  "session_id": "phone_sess_001"
}

---

Approval Workflow

Approve or Reject Action

Approve or reject a pending action from the agent workflow. When the agent requires human approval for sensitive operations (e.g., refunds, inventory adjustments), the workflow pauses at the human_approval node.

POST /api/v1/agent/approve

Request Body

{
  "session_id": "sess_abc",
  "thread_id": "sess_abc",
  "approved": true,
  "approver_id": "manager_123",
  "reason": "Approved inventory adjustment"
}

Field	Type	Required	Description
session_id	string	Yes	Session identifier
thread_id	string	Yes	LangGraph thread identifier
approved	boolean	Yes	Whether the action is approved
approver_id	string	Yes	User approving or rejecting
reason	string	No	Reason for the decision

Response

{
  "response": "Inventory adjustment has been applied. 10 units of ribeye added to stock.",
  "status": "completed"
}

Field	Type	Description
response	string	Agent's response after resuming the workflow
status	string	Always "completed" after approval resolution

---

Conversation History

Get Session History

Retrieve the conversation history and current state for a session.

GET /api/v1/agent/history/{session_id}

Path Parameters

Parameter	Type	Description
session_id	string	Session identifier

Response

{
  "messages": [
    {
      "role": "human",
      "content": "What's our current inventory of ribeye?"
    },
    {
      "role": "ai",
      "content": "Based on your inventory records, you currently have 45 ribeye steaks in stock..."
    }
  ],
  "current_state": [],
  "requires_approval": false
}

Field	Type	Description
messages	array	Array of message objects with role and content
current_state	array	The next nodes to execute in the LangGraph state machine (empty if completed)
requires_approval	boolean	Whether the workflow is paused at human_approval

---

Agent Status

Get Agent Availability

Check whether the LangGraph agent is available and ready.

GET /api/v1/agent/status

Response

{
  "available": true,
  "message": "LangGraph agent ready"
}

When LangGraph is not installed, returns:

{
  "available": false,
  "message": "LangGraph not installed"
}

---

Content Generation

Generate Content Suggestion

AI-powered content generation using the Content Suggestion LangGraph agent. Generates social media content ideas, drafts posts per platform, and provides predicted performance metrics.

POST /api/v1/agent/content/suggestion

Request Body

{
  "topic": "Valentine's Day dinner special",
  "platforms": ["instagram", "facebook", "twitter"],
  "tone": "romantic",
  "context": "We're running a prix fixe Valentine's dinner at $89/couple",
  "industry": "restaurant"
}

Field	Type	Required	Description
topic	string	Yes	Content topic
platforms	array	Yes	Target platforms (e.g., instagram, facebook, twitter)
tone	string	Yes	Content tone (e.g., romantic, casual, professional)
context	string	No	Additional context for the content
industry	string	No	Industry context for better suggestions

Response

{
  "ideas": [
    "Highlight the chef's special courses",
    "Share a behind-the-scenes prep video",
    "Feature a couples' testimonial from last year"
  ],
  "posts": [
    {
      "platform": "instagram",
      "content": "Love is in the air... and so is the aroma of our Valentine's prix fixe...",
      "hashtags": ["#ValentinesDay", "#DateNight"]
    }
  ],
  "analysis": {
    "predicted_engagement": "high",
    "best_posting_time": "6:00 PM"
  }
}

---

Upsell Suggestions

Generate Upsell

Generate AI-powered upsell suggestions based on the current cart contents.

POST /api/v1/agent/upsell

Request Body

{
  "cart_items": [
    {"item_id": "burger-001", "name": "Classic Burger", "price": 12.99}
  ],
  "user_id": "user_123",
  "tenant_id": "restaurant-1",
  "session_id": "sess_abc"
}

Field	Type	Required	Description
cart_items	array	Yes	Array of cart item objects
user_id	string	Yes	User identifier
tenant_id	string	Yes	Tenant identifier
session_id	string	Yes	Session identifier

Response

{
  "suggestions": [
    {
      "item_id": "fries-001",
      "name": "Classic Fries",
      "reason": "Frequently ordered with Classic Burger",
      "confidence": 0.92
    }
  ],
  "analysis": "Based on popular pairings, fries and a drink would complement this order."
}

---

Error Responses

Status	Code	Description
400	invalid_context	Missing required context fields
401	unauthorized	Invalid or missing JWT token
403	feature_disabled	The ai.enabled feature gate is not active
404	session_not_found	Session ID not found in LangGraph state
503	langgraph_unavailable	LangGraph dependencies not installed

---

Related Documentation

• LangGraph Agents Guide - Agent setup
• AI Safety - Safety guidelines
• ACP Router - Model routing