Skip to main content
The AI agents service lives in apps/ai-agents. It runs a LangGraph agent runtime that powers agentic CRM chat and meeting intelligence features.

​
Prerequisites

  • Repo cloned and dependencies installed (bun install)
  • Backend running at http://localhost:3001
  • OPENAI_API_KEY available

​
Environment variables

Copy the example file: 
cp apps/ai-agents/.env.example apps/ai-agents/.env

​
Database

# PostgreSQL — used for LangGraph checkpoint storage
# Can be omitted if set in root .env
DATABASE_URL=postgres://postgres:password@localhost:5432/zuko_dev

​
OpenAI

# Can be omitted if set in root .env
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4.1

​
Backend connection

BACKEND_URL=http://localhost:3001
AGENT_TOKEN=your-agent-token

​
Tracing (optional)

LANGSMITH_TRACING=false
LANGSMITH_API_KEY=
AGENT_TOKEN must be the same value in both apps/backend/.env and apps/ai-agents/.env. It authenticates the agents service when calling backend endpoints.

​
Start the development server

bun nx run @zuko/ai-agents:dev
The service starts at http://localhost:8080 and also opens LangGraph Studio for visual debugging of agent graphs.
The first start may be slow — the LangGraph CLI downloads additional dependencies on first run.

​
LangGraph Studio

When the service is running, open LangGraph Studio at http://localhost:8080 to:
  • Visualize agent execution graphs
  • Inspect state at each step
  • Replay and debug agent runs
  • Test individual graph nodes

​
Useful commands

bun nx run @zuko/ai-agents:dev      # Start with LangGraph Studio
bun nx run @zuko/ai-agents:build    # Production build
bun nx run @zuko/ai-agents:lint     # Lint

​
Troubleshooting

  • Ensure OPENAI_API_KEY is set in apps/ai-agents/.env or root .env
  • Ensure AGENT_TOKEN matches the value in apps/backend/.env
  • The first start may be slow (downloading LangGraph CLI dependencies) — wait a minute before retrying
lsof -ti:8080 | xargs kill -9
To enable tracing for debugging:
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=your-langsmith-api-key
LANGSMITH_PROJECT=zuko
Sign up at smith.langchain.com to get an API key.
The agents service uses PostgreSQL for LangGraph checkpointing. Ensure DATABASE_URL is set and the zuko_dev database exists:
createdb zuko_dev
bun nx run @zuko/models:prisma:migrate -- --name init