A visual AI agent workflow builder that lets you design, test, and deploy multi-step agent flows without writing code. Draw a graph on the canvas, configure each node, and run it live against AWS Bedrock — or deploy the entire agent to AWS AgentCore Runtime where each session runs in an isolated microVM.
- What this is
- Architecture
- Project structure
- Quick start
- Configuration
- The visual builder
- Node catalog
- Writing flow JSON
- Flow library
- Observability dashboard
- API server
- Python execution engine
- Deploying to AWS AgentCore Runtime
- Security
- Troubleshooting
Most agent frameworks require you to write code for every new agent. Valogent inverts that — the agent is the graph, not the code.
You place nodes on a canvas, connect them with edges, and configure each node with a form. The builder serialises the canvas to a flow JSON file. The Python execution engine reads that JSON, compiles it into a LangGraph StateGraph at runtime, and executes it. The same engine runs any flow — healthcare claims, invoice approval, document processing, customer support — with no code changes.
You draw a graph → Builder writes JSON → Engine executes the graph
The engine is domain-free. No business logic, hardcoded field names, or service registries live in the engine code. Everything domain-specific — mock responses, test scenarios, prompt templates — lives inside the flow JSON alongside the flow definition itself.
┌──────────────────────────────────────────────────────────────────┐
│ Valogent UI (React 18 + Vite 5) │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌──────────────────┐ │
│ │ Flow Library │ │ Canvas Builder│ │ API Tester │ │
│ │ (Zustand + │ │ (ReactFlow + │ │ (invoke live │ │
│ │ MongoDB) │ │ node palette)│ │ AgentCore) │ │
│ └────────────────┘ └────────────────┘ └──────────────────┘ │
└───────────────────────────────┬──────────────────────────────────┘
│ REST + SSE
┌───────────────────────────────▼──────────────────────────────────┐
│ Express API Server (Node.js / ESM) │
│ api/server.js │
│ │
│ POST /ai/run-server → streams flow execution via SSE │
│ POST /ai/chat → AI canvas assistant (Claude) │
│ GET /api/library → flow CRUD (MongoDB / DocumentDB) │
│ POST /api/invoke/:id → invoke deployed AgentCore runtime │
│ GET /api/observability → CloudWatch + local invocation metrics │
└───────┬───────────────────────────────────────┬──────────────────┘
│ boto3 / Bedrock SDK │ InvokeAgentRuntime
▼ ▼
┌───────────────────┐ ┌────────────────────────────────┐
│ AWS Bedrock │ │ AWS AgentCore Runtime │
│ Claude (Converse │ │ server/main.py → LangGraph │
│ Stream API) │ │ Each session: isolated microVM│
└───────────────────┘ │ Auto-scale 0→N, 8-hr window │
└────────────────────────────────┘
│
▼
┌───────────────────┐ ┌───────────────┐ ┌──────────────────────┐
│ MongoDB / │ │ CloudWatch │ │ External APIs │
│ DocumentDB │ │ AWS/Bedrock │ │ EHR · Payer · Slack │
│ flows + │ │ -AgentCore │ │ MCP servers │
│ invocations │ │ namespace │ └──────────────────────┘
└───────────────────┘ └───────────────┘
Every node reads from and writes to a single shared state dict. Each node writes its output under its own id key — state["n2_docs"]["output"], state["n5_coding"]["output"], etc. State is append-only: you always have a complete audit trail.
Node configs use {{state.node_id.output.field}} template expressions to wire one node's output to another node's input:
Canvas edge: n2_docs.output.cpt_codes → n5_coding.input.cpt_codes
Flow JSON: "cpt_codes": "{{state.n2_docs.output.cpt_codes}}"
Runtime: engine reads state["n2_docs"]["output"]["cpt_codes"]
and passes it into the Claude prompt as {cpt_codes}
agent-builder/
│
├── server/ # Python execution engine
│ ├── agent_engine.py # Graph compilation + CLI entry point
│ ├── utils.py # All node handlers, mock tools, LLM client
│ ├── config.py # .env loading, AWS session factory
│ ├── main.py # AgentCore Runtime entrypoint (POST /invocations)
│ ├── deploy_agentcore.py # Packages + deploys to AgentCore Runtime
│ ├── invoke_agentcore.py # Invokes the deployed runtime endpoint
│ ├── rcm_flow.json # Example flow — healthcare RCM
│ ├── invoice_flow.json # Example flow — finance invoice approval
│ ├── requirements.txt
│ ├── global-bundle.pem # DocumentDB TLS CA cert
│ └── .env # credentials — never commit
│
└── ui/ # Valogent frontend + API server
├── index.html
├── package.json
├── vite.config.js
│
├── api/ # Express API server (runs alongside Vite)
│ ├── server.js # All REST + SSE endpoints
│ ├── db.js # MongoDB / DocumentDB connection
│ └── seed_flows.js # Seed example flows into DB
│
└── src/
├── main.jsx
├── App.jsx # Page router (library / builder / tester)
├── App.css # All styles (dark + light theme, CSS vars)
├── store.js # Zustand state (flows, canvas, UI, observability)
├── constants.js # Node catalog, node type metadata
├── utils.js # Flow ↔ ReactFlow conversion, layout
│
├── components/
│ ├── TopBar.jsx # Header (logo, save, deploy, theme toggle)
│ ├── NodePalette.jsx # Collapsible left rail + flyout node picker
│ ├── FlowCanvas.jsx # ReactFlow canvas
│ ├── AgentNode.jsx # Custom node renderer
│ ├── NodeConfigPanel.jsx # Right panel — selected node config form
│ ├── FlowJsonPanel.jsx # JSON viewer (panel) + JSON editor (modal)
│ ├── BottomPanel.jsx # Run log + test runner
│ └── AIAssistant.jsx # Claude AI canvas assistant (floating chat)
│
└── pages/
├── LibraryPage.jsx # Flow grid + observability dashboard
└── TesterPage.jsx # Live API tester (invoke AgentCore)
- Node.js 20+ and npm
- Python 3.11+
- AWS account with Bedrock model access enabled (
ap-southeast-1or your region) - MongoDB running locally (
mongodb://localhost:27017) or a DocumentDB / Atlas URI
# UI + API server
cd ui
npm install
# Python engine
cd ../server
pip install langgraph boto3 python-dotenv bedrock-agentcore bedrock-agentcore-starter-toolkitCreate server/.env:
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_SESSION_TOKEN=your_session_token # only for temporary/SSO credentials
AWS_REGION=ap-southeast-1
BEDROCK_MODEL_ID=apac.anthropic.claude-3-haiku-20240307-v1:0
AGENT_FLOW_FILE=rcm_flow.json
DOCUMENTDB_URI=mongodb://localhost:27017
DOCUMENTDB_DB=agent_builderVerify AWS credentials load correctly:
cd server && python config.py
# Prints your account ID and user ARNcd ui
npm run devThis starts two processes concurrently:
- Vite dev server on
http://localhost:5173(the UI) - Express API server on
http://localhost:3001(REST + SSE)
Open http://localhost:5173 in your browser.
cd ui
node api/seed_flows.jsAll configuration is read from server/.env. The API server reads the same file at startup.
| Variable | Required | Default | Description |
|---|---|---|---|
AWS_ACCESS_KEY_ID |
Yes | — | AWS access key |
AWS_SECRET_ACCESS_KEY |
Yes | — | AWS secret key |
AWS_SESSION_TOKEN |
No | — | Temporary credential session token (SSO / AssumeRole) |
AWS_REGION |
Yes | us-east-1 |
AWS region for Bedrock and AgentCore |
BEDROCK_MODEL_ID |
No | apac.anthropic.claude-3-haiku-20240307-v1:0 |
Default Bedrock model |
AGENT_FLOW_FILE |
No | rcm_flow.json |
Default flow for the AgentCore entrypoint |
DOCUMENTDB_URI |
Yes | — | MongoDB or DocumentDB connection string |
DOCUMENTDB_DB |
No | agent_builder |
Database name |
DocumentDB (production): The connection automatically uses TLS + server/global-bundle.pem when the URI contains .docdb.amazonaws.com.
Model options (ap-southeast-1):
BEDROCK_MODEL_ID=apac.anthropic.claude-3-haiku-20240307-v1:0 # fastest
BEDROCK_MODEL_ID=apac.anthropic.claude-3-5-sonnet-20241022-v2:0 # best reasoning
BEDROCK_MODEL_ID=apac.anthropic.claude-3-opus-20240229-v1:0 # most capableThe canvas is a ReactFlow graph editor. Drag nodes from the left palette onto the canvas. Connect nodes by dragging from one handle to another. Click a node to open the config panel on the right.
Toolbar (top bar):
- ← Library — return to the flow library
- Save — save to MongoDB and return to library
- Auto-layout — arrange nodes with dagre
- Run — execute the current flow against AWS Bedrock
- Deploy — package and deploy to AgentCore Runtime
- Theme — toggle dark / light mode
- { } — open the JSON panel for the current flow
The left rail is collapsible. Click the chevron at the bottom to collapse it to icon-only mode. Click any category button to expand a flyout showing all node types in that category. Drag a node type onto the canvas to add it.
View mode (right panel, always visible when open): read-only CodeMirror viewer with syntax highlighting. Click { } in the top bar to toggle.
Edit mode (full-screen modal): click Edit in the panel header. Opens a full-screen CodeMirror editor with:
- JSON syntax highlighting (keys, strings, numbers, booleans each in distinct colours)
- Live JSON validation — a red Invalid JSON badge appears on parse errors
- Apply — parses and loads the edited JSON into the canvas
- Cancel / Escape — discard changes
Click the floating AI button (bottom-right) to open a chat panel. Describe what you want to build — the assistant generates or modifies the flow on the canvas in real time using tool calls (load_full_flow, add_node, add_edge).
Open the bottom panel (Run tab) and click Run Flow. The panel streams node-by-node execution via SSE, showing status indicators (running → done / error) on each canvas node in real time. Final state is displayed when execution completes.
Valogent includes 35+ built-in node types across 7 categories.
| Type | Description |
|---|---|
trigger.http |
Entry point — receives the HTTP request body as state["input"] |
trigger.schedule |
Run on a cron schedule |
trigger.event |
Listen for an event from a bus or queue |
trigger.webhook |
Receive an inbound webhook from an external service |
| Type | Description |
|---|---|
llm.bedrock |
AWS Bedrock model call (Claude, Titan, etc.) |
llm.anthropic |
Anthropic Claude via direct API |
llm.openai |
OpenAI API call |
llm.gemini |
Google Gemini via Vertex AI |
llm.groq |
Groq fast-inference API |
llm.ollama |
Local Ollama model |
| Type | Description |
|---|---|
data.rest_api |
HTTP service call |
data.graphql |
GraphQL query or mutation |
data.db_write |
Write record to database |
data.db_read |
Read from database |
data.s3_read |
Read file from S3 |
data.s3_write |
Write file to S3 |
data.kafka_publish |
Publish message to Kafka topic |
data.redis_get |
Read key from Redis |
data.redis_set |
Write key to Redis |
| Type | Description |
|---|---|
flow.router |
Reads a value from state, branches to one of N paths |
flow.human_in_loop |
Pause for human review; auto-resolves in mock mode |
flow.loop |
Increment an iteration counter; wire a back-edge to loop |
flow.sub_agent |
Call another deployed agent by ID |
| Type | Description |
|---|---|
doc.pdf_parser |
Extract structured fields from PDF via OCR |
doc.ocr |
Extract raw text from image or scanned document |
doc.html_scraper |
Scrape structured data from a web page |
doc.email_parser |
Parse inbound email (headers, body, attachments) |
| Type | Description |
|---|---|
mcp.slack |
Post message to Slack via Slack MCP server |
mcp.notion |
Create/update Notion page via Notion MCP server |
mcp.github |
Interact with GitHub via GitHub MCP server |
mcp.<custom> |
Any unrecognised mcp.* type falls back to MockTools.generic |
| Type | Description |
|---|---|
memory.vector_write |
Write documents to a vector store |
memory.vector_read |
Query a vector store by semantic similarity |
A flow JSON file has five sections:
{
"agent_id": "ag_my_agent",
"name": "My Agent",
"description": "What this agent does",
"nodes": [...],
"edges": [...],
"prompt_templates": {},
"test_scenarios": {},
"mock_llm_responses": {}
}{
"id": "n1_trigger",
"type": "trigger.http",
"config": {}
}Input values use {{state.node_id.output.field}} templates to wire outputs from previous nodes:
{
"id": "n4_eligibility",
"type": "data.rest_api",
"config": {
"service": "eligibility",
"input_map": {
"member_id": "{{state.n3_ehr.output.member_id}}",
"payer_id": "{{state.input.payer_id}}",
"service_date": "{{state.n2_docs.output.service_date}}"
}
}
}{ "from": "n3_ehr", "to": "n4_eligibility" },
{ "from": "n6_router", "to": "n7a_submit", "condition": "clean" },
{ "from": "n6_router", "to": "n7b_review", "condition": "needs_fix" }{
"id": "n6_router",
"type": "flow.router",
"config": {
"branch_on": "{{state.n5_coding.output.status}}",
"conditions": [
{ "if": "status == 'clean'", "goto": "n7a_submit" },
{ "if": "status == 'needs_fix'", "goto": "n7b_review" },
{ "if": "status == 'denial'", "goto": "n7c_appeal" }
],
"default_goto": "n7b_review"
}
}{
"id": "n5_coding",
"type": "llm.bedrock",
"config": {
"model_id": "apac.anthropic.claude-3-haiku-20240307-v1:0",
"prompt_template": "tmpl_coding_validate",
"input_map": {
"cpt_codes": "{{state.n2_docs.output.cpt_codes}}",
"icd10": "{{state.n2_docs.output.icd10_codes}}"
}
}
}Prompt templates live in the top-level prompt_templates object:
"prompt_templates": {
"tmpl_coding_validate": "You are a medical coding expert. Validate these CPT codes: {cpt_codes} for diagnoses: {icd10}. Return JSON: {\"status\": \"clean|needs_fix|denial\", \"issues\": [], \"recommendation\": \"\"}"
}Every node that calls an external service accepts a mock_response field:
{
"id": "n3_ehr",
"type": "data.rest_api",
"config": {
"service": "ehr",
"input_map": { "patient_id": "{{state.input.patient_id}}" },
"mock_response": {
"member_id": "MBR_9927",
"diagnoses": ["Z23", "J06.9"],
"auth_codes": ["99213", "87880"]
}
}
}"test_scenarios": {
"needs_fix": {
"claim_id": "CLM_8821",
"patient_id": "PT_4492",
"payer_id": "BCBS_TX"
}
},
"mock_llm_responses": {
"needs_fix": [
"{\"status\": \"needs_fix\", \"confidence\": 0.91, \"issues\": [\"CPT 93000 not authorized\"]}"
]
}Multiple LLM nodes that fire sequentially get one response string each, in order:
"mock_llm_responses": {
"denial": [
"{\"status\": \"denial\", \"issues\": [...]}",
"{\"appeal_letter\": \"Dear Payer...\", \"priority\": \"urgent\"}"
]
}The library page lists all saved flows stored in MongoDB. Each flow card shows:
- Node category chips (colour-coded by type)
- Node count and edge count
- Last updated time
Actions per flow: Open in builder, Duplicate, Delete.
Import: Upload a .json file to add it to the library. The flow is immediately persisted.
Sort + search: filter by name or description; sort by last updated, name, or node count.
Flows are stored in the flows collection in MongoDB / DocumentDB. The API server exposes:
GET /api/library — list all flows
POST /api/library — upsert a flow (by agent_id)
DELETE /api/library/:flow_id — delete a flow
The library page includes a live observability section below the flow grid, pulling data from two sources.
Every execution — whether via the in-builder Run panel or via a direct POST /api/invoke/:flow_id — writes a record to the invocations MongoDB collection:
{
"flow_id": "ag_rcm_001",
"flow_name": "RCM Claims Agent",
"session_id": "sess-abc123",
"status": "success",
"duration_ms": 1842,
"nodes_executed": 8,
"invoked_at": "2025-04-21T08:23:11.000Z"
}Summary metrics:
- Total Invocations · Success Rate · Avg Duration · Active Flows
Per-flow stats table: invocation count, success rate bar, avg duration, last run time.
Recent invocations list: scrollable, fixed height. Click any row to expand an inline detail drawer showing:
- Status pill (green success / red error)
- Flow ID · Session ID · Duration · Full timestamp
- Nodes executed · Total nodes
- Full error message (if any)
- Input / Output JSON (if recorded)
The observability endpoint also fetches real metrics from CloudWatch namespace AWS/Bedrock-AgentCore, scoped to your deployed runtime ARN via the Resource dimension.
Namespace and dimension are auto-discovered on first request via ListMetrics (no hardcoding required). The server logs confirm the discovery:
[CW] probe "CPUUsed-vCPUHours" → namespace=AWS/Bedrock-AgentCore dimName=Resource
8 CloudWatch metric cards (last 24 hours):
| Metric | CloudWatch name | Stat |
|---|---|---|
| Invocations | Invocations |
Sum |
| Throttle Rate | Throttles / Invocations |
Computed % |
| Error Rate | (SystemErrors + UserErrors) / Invocations |
Computed % |
| Avg Latency | Latency |
Average |
| Session Count | SessionCount |
Sum |
| CPU usage | CPUUsed-vCPUHours |
Sum |
| Memory usage | MemoryUsed-GBHours |
Sum |
Runtime Logs: a collapsible panel streams the last 50 CloudWatch Log events from the /aws/bedrock-agentcore log group, auto-discovered via DescribeLogGroups.
The discovered namespace is shown in the section header so you can verify which namespace data is coming from.
ui/api/server.js is a Node.js/Express server that runs alongside the Vite dev server.
| Method | Path | Description |
|---|---|---|
POST |
/ai/run-server |
Execute a flow JSON against AWS Bedrock; streams node_start, node_done, flow_done events via SSE |
POST |
/ai/chat |
Claude AI canvas assistant; streams tool calls (load_full_flow, add_node, add_edge) |
GET |
/api/library |
List all saved flows |
POST |
/api/library |
Upsert a flow |
DELETE |
/api/library/:id |
Delete a flow |
GET |
/api/deployed-flows |
List flows registered as deployed AgentCore runtimes |
POST |
/api/invoke/:flow_id |
Invoke a deployed AgentCore runtime for the given flow |
GET |
/api/observability |
Aggregate CloudWatch + MongoDB invocation metrics |
New service in an existing category: add a static method to MockTools in server/utils.py. No registry update needed — MCPHandler auto-routes to it by name.
New category: add a handler class to utils.py and register it in NodeRegistry.REGISTRY:
REGISTRY: dict[str, Any] = {
"trigger": TriggerHandler,
"doc": DocHandler,
"data": DataHandler,
"llm": LLMHandler,
"flow": FlowHandler,
"mcp": MCPHandler,
"memory": MemoryHandler,
"crm": CRMHandler, # ← new
}agent_engine.py never needs to change.
| File | Responsibility |
|---|---|
config.py |
Loads .env, exposes typed settings + get_boto3_client() |
utils.py |
All node handlers, NodeRegistry, MockTools, LLM client |
agent_engine.py |
build_graph() — compiles flow JSON → LangGraph StateGraph; CLI entry |
main.py |
AgentCore HTTP contract (@app.entrypoint, /invocations, /ping) |
deploy_agentcore.py |
IAM + S3 + AgentCore packaging and deployment |
invoke_agentcore.py |
InvokeAgentRuntime wrapper with streaming + session support |
# Mock mode (no Bedrock cost)
python agent_engine.py --flow rcm_flow.json --scenario needs_fix --mock
# Live Bedrock
python agent_engine.py --flow rcm_flow.json --scenario clean
# Different domain, same engine
python agent_engine.py --flow invoice_flow.json --scenario auto_approve --mock
# Raw input instead of a named scenario
python agent_engine.py --flow rcm_flow.json --mock \
--input '{"claim_id":"CLM_001","patient_id":"PT_99","payer_id":"BCBS","docs":[]}'# Terminal 1
python main.py # starts HTTP server on :8080
# Terminal 2
curl http://localhost:8080/ping
curl -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{"flow": "rcm_flow.json", "scenario": "needs_fix", "mock": true}'AgentCore Runtime hosts your agent in a managed, serverless environment. Each session runs in a dedicated microVM with completely isolated CPU, memory, and filesystem.
bedrock-agentcore:CreateAgentRuntime
bedrock-agentcore:UpdateAgentRuntime
bedrock-agentcore:GetAgentRuntime
bedrock-agentcore:InvokeAgentRuntime
iam:CreateRole iam:PutRolePolicy iam:GetRole
s3:CreateBucket s3:PutObject s3:GetObject s3:PutBucketVersioning
# Step 1 — test entrypoint locally (see above)
# Step 2 — deploy
cd server
python deploy_agentcore.pydeploy_agentcore.py:
- Creates IAM execution role
AgentCoreRuntimeRole-RCM - Creates an S3 bucket for the deployment package
- Cross-compiles Python deps for
arm64Linux (AgentCore's architecture) - Zips source + deps, uploads to S3
- Calls
CreateAgentRuntimeand polls untilREADY - Saves runtime ARN + endpoint ARN to
server/.agentcore_deploy.json
# Step 3 — invoke the live runtime
python invoke_agentcore.py --scenario needs_fix --mock
python invoke_agentcore.py --scenario clean
python invoke_agentcore.py --session-id sess-abc123 --scenario denial # reuse session
# Update after code changes
python deploy_agentcore.py --update --runtime-arn <arn> # full redeploy
python deploy_agentcore.py --update --runtime-arn <arn> --skip-zip # code only{
"flow": "rcm_flow.json",
"scenario": "needs_fix",
"mock": false,
"input": {
"claim_id": "CLM_8821",
"patient_id": "PT_4492",
"payer_id": "BCBS_TX",
"docs": ["s3://bucket/claim.pdf"]
}
}input overrides scenario when both are provided.
{
"status": "success",
"session_id": "sess-abc123",
"branch": "n7a_submit",
"state": {
"input": { "claim_id": "CLM_8821", "..." : "..." },
"n2_docs": { "output": { "cpt_codes": ["99213"] } },
"n5_coding": { "output": { "status": "clean", "confidence": 0.97 } },
"n6_router": { "branch": "n7a_submit" },
"n7a_submit": { "output": { "submission_id": "SUB_093B999B" } }
}
}- Each unique
session_id→ isolated microVM (CPU, memory, filesystem) - 15-minute idle timeout; 8-hour maximum session lifetime
- On termination: microVM wiped, memory sanitised
- Concurrent sessions of the same agent cannot access each other's state
- All credentials live in
server/.env— never hardcoded, never committed .envand.agentcore_deploy.jsonmust be in.gitignore- Temporary credentials (SSO /
sts:AssumeRole) are supported viaAWS_SESSION_TOKEN - Run
python server/config.pyto verify what is loaded
The IAM role created by deploy_agentcore.py has only:
bedrock:InvokeModel— call LLM modelslogs:*— write CloudWatch logss3:GetObjecton the deployment bucket — read the package
server/.env
server/.env.*
server/.agentcore_deploy.json
server/global-bundle.pem
__pycache__/
*.pyc
.venv/
ui/node_modules/
| Error | Cause | Fix |
|---|---|---|
NoCredentialsError |
.env not loaded or empty |
Run python server/config.py to check what is loaded |
AccessDeniedException on Bedrock |
Model not enabled in your region | AWS Console → Bedrock → Model access → enable the model |
ENOENT: package.json not found |
Running npm from project root | cd ui && npm run dev |
DOCUMENTDB_URI is not set |
.env missing or wrong path |
API server reads server/.env — check it exists |
Port 3001 already in use |
Previous API server still running | lsof -i :3001 | kill -9 <PID> |
Port 8080 already in use |
Previous main.py still running |
lsof -i :8080 | kill -9 <PID> |
CloudWatch shows — for all metrics |
Wrong namespace or credentials | Check server log for [CW] probe line; ensure AWS creds have cloudwatch:GetMetricStatistics |
| Router always takes default branch | branch_on path doesn't match state |
Print state after the LLM node to verify the exact key path |
| LLM returns non-JSON | Prompt not constraining output | Add explicit JSON-only instruction to prompt_templates |
NoSuchEntityException on IAM |
Insufficient deploy permissions | Add iam:CreateRole, iam:PutRolePolicy to your deploying user |
Built with React · ReactFlow · Zustand · CodeMirror 6 · Express · LangGraph · AWS Bedrock · AWS AgentCore Runtime · MongoDB