Quick Start

Prerequisites, installation, and first steps walkthrough

Getting Started with the Enterprise Agentic AI Platform

This guide walks you through setting up the development environment, running the platform locally, and taking your first steps with each of the three applications.

Table of Contents

• Prerequisites
• Clone and Install
• Running the Development Server
• The Three Applications
• Mock Authentication
• Understanding the Mock Users
• First Steps Walkthrough
• Infrastructure Services (Optional)
• Environment Variables
• Troubleshooting Common Setup Issues

Prerequisites

Before you begin, make sure you have the following installed:

Installing pnpm

If you do not have pnpm installed, you can install it globally:

npm install -g pnpm@9

Or use Corepack (bundled with Node.js 16+):

corepack enable
corepack prepare pnpm@9.0.0 --activate

Clone and Install

1. Clone the repository:

git clone <repository-url> agentic-platform
cd agentic-platform

1. Install all dependencies:

pnpm install

This installs dependencies for all three applications (portal, studio, admin), the shared packages (ui, api-client, auth, types, config), and the backend services (api-gateway, ws-server).

1. Copy the environment file:

cp .env.example .env

The default .env configuration enables mock mode, which means all API calls return simulated data. No external services are required for frontend development.

Running the Development Server

Start all three applications simultaneously:

pnpm dev

Or start individual applications:

pnpm dev --filter=portal    # Agent Portal only
pnpm dev --filter=studio    # Agent Studio only
pnpm dev --filter=admin     # Admin Console only

Convenience scripts are also available:

pnpm dev:portal    # Same as pnpm dev --filter=portal
pnpm dev:studio    # Same as pnpm dev --filter=studio
pnpm dev:admin     # Same as pnpm dev --filter=admin
pnpm dev:api       # API Gateway only

The Three Applications

The platform is composed of three web applications, each serving a different user persona:

Each application has its own login page and navigation. You can run all three simultaneously.

Mock Authentication

The platform uses mock authentication during development. No real identity provider (IdP) is required. The login page presents a role selector that lets you choose which user persona to log in as.

Logging into the Agent Portal

1. Open http://localhost:3000 in your browser.
2. You will be redirected to the login page at /login.
3. Select the Consumer role card (Alice Consumer).
4. Optionally adjust the tenant and group selections.
5. Click Login.
6. You are redirected to /portal/chat, the default chat page.

Logging into Agent Studio

1. Open http://localhost:3001 in your browser.
2. You will be redirected to the login page at /login.
3. Select the Builder role card (Bob Builder).
4. Click Login.
5. You are redirected to /studio/agents, the agent management page.

Logging into the Admin Console

1. Open http://localhost:3002 in your browser.
2. You will be redirected to the login page at /login.
3. Select the Admin role card (Carol Admin).
4. Click Login.
5. You are redirected to /admin/dashboard, the platform overview dashboard.

Switching Roles

You can log into any application with any role for testing purposes. However, note that the role you choose determines which agents you can see (due to entitlement-based filtering) and which features are available. The mock login page allows you to customize your groups and tenant to test different access scenarios.

Understanding the Mock Users

The platform includes three pre-configured mock users, one for each role:

Groups and Their Effect on Agent Visibility

The mock data includes agents with different entitlement configurations. The agents you see depend on your user's groups:

• Alice (groups: hr-team, all-staff) sees:

  • All public agents (e.g., Customer Support Bot, Developer Assistant, IT Help Desk)
  • She does not see agents restricted to engineering groups.

• Bob (groups: engineering, all-staff) sees:

  • All public agents
  • restricted agents that allow the engineering group (e.g., Research Analyst)

• Carol (groups: executives, all-staff) sees:

  • All public agents
  • restricted agents that allow the admin role

Available Groups for Testing

You can customize groups at login time. The available groups are:

• engineering -- Engineering team
• hr-team -- Human Resources team
• finance -- Finance department
• executives -- Executive leadership
• all-staff -- All employees (assigned to everyone by default)

Available Tenants

Two tenants are available for multi-tenancy testing:

• tenant-1 -- Acme Corporation (default)
• tenant-2 -- Globex Industries

First Steps Walkthrough

Step 1: Explore the Agent Portal as Alice

1. Open http://localhost:3000 and log in as Consumer (Alice).
2. Navigate to Agent Catalog (/portal/agents):
   • Browse the available agents. You should see agents like "Customer Support Bot", "Developer Assistant", and "IT Help Desk" (public agents).
   • Use the filter buttons to filter by runtime (Pro-Code, n8n) or status (Active, Canary, Draft).
   • Use the search bar to find agents by name or description.
3. Click on an agent card (e.g., "Customer Support Bot") to start a conversation:
   • You are taken to the chat interface at /portal/chat/agent-1.
   • Type a message and press Enter to send it.
   • Observe the streaming response from the agent, including tool usage indicators.
   • Use the conversation sidebar on the left to switch between conversations or start a new chat.
4. Visit Approvals (/portal/approvals) to see pending Human-in-the-Loop requests.
5. Check History (/portal/history) for past conversations.
6. Browse Workflows (/portal/workflows) for pre-configured workflow triggers.

Step 2: Explore Agent Studio as Bob

1. Open http://localhost:3001 and log in as Builder (Bob).
2. Browse the Agent List (/studio/agents):
   • See all agents you own or have access to.
   • Click the Create Agent button or navigate to /studio/agents/new to start building a new agent.
3. Click on an existing agent to open the Agent Designer (/studio/agents/[id]):
   • Explore the tabbed interface: Prompt, Model, Tools, Access, Identity, Interactions, Memory, Safety, Deploy.
   • Each tab configures a different aspect of the agent.
4. Visit Tools (/studio/tools) to browse the MCP tool registry.
5. Check Traces (/studio/traces) to explore execution traces with span-level detail.
6. Open Monitoring (/studio/monitoring) for agent performance metrics.
7. Explore Models (/studio/models) to see available LLM models and their configurations.
8. Use the Playground (/studio/playground) to test agents interactively.

Step 3: Explore the Admin Console as Carol

1. Open http://localhost:3002 and log in as Admin (Carol).
2. View the Dashboard (/admin/dashboard):
   • See platform-wide health metrics, active agents, and system status.
3. Browse Agents (/admin/agents) for administrative agent management:
   • View all agents across the platform.
   • Access the privilege report and access topology visualizations.
4. Manage Security (/admin/security) for access control oversight.
5. Review Policies (/admin/policies) for Cedar policy management.
6. Check Audit (/admin/audit) for the decision audit log.
7. Monitor FinOps (/admin/finops) for cost attribution and spend tracking.
8. View Guardrails (/admin/guardrails) for safety event monitoring.
9. Manage Compliance (/admin/compliance) for regulatory reporting.
10. Monitor Infrastructure (/admin/infrastructure) for system health metrics.

Infrastructure Services (Optional)

For frontend-only development, infrastructure services are not required. The platform runs in mock mode by default, returning simulated data for all API calls.

If you want to run backend services for integration testing, start them with Docker Compose:

docker-compose up -d

This starts the core and extended infrastructure services:

Core Services

Identity & Security

Observability

n8n & Agent Runtime

Storage

Additional Services (Optional)

• Neo4j -- Graph database for relationship memory and knowledge graphs
• Kafka -- Event bus for asynchronous agent communication and audit logging

Stopping Infrastructure

docker-compose down        # Stop containers, keep data
docker-compose down -v     # Stop containers and delete data volumes

Environment Variables

Copy .env.example to .env and configure as needed:

cp .env.example .env

Key Variables

Mock Mode

When MOCK_MODE=true (the default), all API calls return simulated data from the mock data layer. This allows full frontend development without any backend services running. The mock data includes:

• 6 pre-configured agents with different runtimes, statuses, and entitlements
• Conversations with message history and tool call examples
• Pending approval requests for HITL testing
• 10 MCP tools with different risk levels and categories
• Execution traces with span-level detail
• Platform users, groups, and tenants
• Policies, audit entries, and compliance reports

Troubleshooting Common Setup Issues

pnpm: command not found

pnpm is not installed. Install it with:

npm install -g pnpm@9

node: No such file or directory or Node.js version too old

Ensure Node.js 18+ is installed. Use a version manager like nvm to install and switch versions:

nvm install 18
nvm use 18

Port already in use (EADDRINUSE)

Another process is using port 3000, 3001, or 3002. Find and terminate it:

# Find the process using port 3000
lsof -i :3000

# Kill it
kill -9 <PID>

Or change the port in each app's configuration.

Dependency installation fails

Clear pnpm's cache and node_modules, then reinstall:

pnpm store prune
rm -rf node_modules
rm -rf apps/*/node_modules packages/*/node_modules services/*/node_modules
pnpm install

Blank page or hydration errors

1. Ensure you are running pnpm dev (not pnpm build followed by pnpm start during development).
2. Clear browser cache and local storage.
3. Check the browser console for specific error messages.

Login redirects back to the login page

The mock authentication stores session data in localStorage. If the login does not persist:

1. Ensure cookies and localStorage are not blocked by browser settings.
2. Clear localStorage for localhost and try again.
3. Check that NEXTAUTH_URL in .env matches the URL you are accessing.

Docker Compose fails to start

1. Ensure Docker Desktop (or Docker Engine) is running.
2. Check for port conflicts with existing services on ports 5432, 6379, 6333, or 6334.
3. On macOS/Linux, ensure your user has Docker permissions.

TypeScript errors after pulling new changes

Rebuild the shared packages:

pnpm build --filter=@agentic/types --filter=@agentic/ui --filter=@agentic/api-client --filter=@agentic/auth

Then restart the dev server.

Build fails with turbo errors

Ensure Turborepo is installed as a dev dependency (it should be via pnpm install). If not:

pnpm add -D turbo -w

Next Steps

• For business users: Read the Using Agents Guide to learn how to interact with agents in the Portal.
• For builders: Read the Registering Agents Guide to learn how to create and configure agents in Studio.
• For n8n builders: n8n Workflow Templates guide (coming soon — the n8n integration is temporarily disabled).
• For tool developers: Read the Tool Integration Guide to learn how to register and integrate MCP tools.
• For testing & evaluation: Read the Eval Suite & Playground Guide for systematic agent quality testing.
• For access control setup: Read the Builder Access Control Guide for the four-dimensional access control model.

Your First API Call

Once the platform is running, try these commands to verify everything works.

1. Get a token

TOKEN=$(curl -s -X POST http://localhost:4000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"userId":"user-builder-1","role":"builder","tenantId":"tenant-1"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")

2. List agents

curl -s http://localhost:4000/api/agents \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool | head -20

3. Chat with an agent

curl -N http://localhost:4000/api/chat/agent-1/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"message":"Hello, what can you do?"}'

This returns an SSE stream. You'll see events like TEXT_MESSAGE_CONTENT, TOOL_CALL_START, and RUN_FINISHED.

4. Browse the API

Open the interactive API Explorer at http://localhost:3003/api-explorer or view the OpenAPI spec directly:

curl -s http://localhost:4000/api/openapi.json | python3 -m json.tool | head -10

See the full API Reference for all endpoints.

Related Documentation

• Architecture Reference -- Full platform architecture (10 layers)
• UI Specification -- Screen inventory and wireframes (30 screens)
• Implementation Plan -- Phased build plan
• LLM Provider Configuration -- T-Systems AIFS setup
• Access Control Reference -- Full access control model
• AG-UI + A2A Protocol Reference -- Turn-based execution protocol