Agent Node (Main Card)

The main agent card is the heart of your AI agent. It defines personality, behavior, model selection, and permissions.

Overview

Always present: Every project has exactly 1 main agent card Location: Center of canvas by default Color: Gradient purple/blue Icon: Customizable (emoji or custom image) Required: Yes (cannot be deleted) [Screenshot: Main agent card with labeled components] Purpose:

Define agent personality and behavior via system prompt
Select AI model (Claude Opus/Sonnet/Haiku)
Configure permissions and sandbox settings
Set temperature, max tokens, and other parameters
Connect to all other node types (skills, memory, MCPs, etc.)

Configuration Sections

1. Basic Information

Name

Agent’s display name shown in chat interface
Appears in dashboard project cards
Used in exported .claude folder

Examples:

✅ Good: Email Summarizer, Code Reviewer, Research Assistant
❌ Generic: Agent, My Bot, Untitled

Description

Brief summary of agent’s purpose
Internal documentation (not sent to Claude)
Shows on dashboard cards

Examples:

✅ "Analyzes emails and suggests appropriate responses"
✅ "Reviews code for security issues and style violations"
✅ "Researches topics and generates comprehensive reports"

Icon

Visual identifier for your agent
Emoji or custom image (PNG, JPG)
Click icon to change

Popular choices:

📧 Email handler
💻 Code reviewer
📊 Data analyzer
🔍 Researcher
💬 Chatbot

[Screenshot: Basic info panel with name, description, and icon fields]

2. System Prompt

The system prompt is the most important configuration. It defines your agent’s:

Role and personality
Instructions and guidelines
Output format
Constraints and limitations

Location: Large text area in configuration panel Best Practices:

✅ Do:

1. Start with clear role definition

You are a [specific role]. Your purpose is to [clear objective].

2. Use structured instructions

When given [input], you should:
[First step]
[Second step]
[Third step]

3. Define output format explicitly

## Output Format
📧 **Email Summary:**
• [Key point 1]
• [Key point 2]

**Intent:** [Classification]
**Action:** [Recommendation]

4. Set tone and personality

Tone: Professional, friendly, concise
Style: Direct answers, minimal jargon

5. Specify constraints

Constraints:
- Keep responses under 500 words
- Always cite sources
- Ask for clarification if ambiguous

❌ Don’t:

1. Vague instructions

❌ You are helpful. Please assist the user.

2. Conflicting directives

❌ Be very detailed but also extremely concise.

3. Overly long prompts

❌ [5000+ character prompt with every possible scenario]

4. Assume implicit knowledge

❌ Follow our standard process.  # What process?

Example System Prompts

Example 1: Email Summarizer

You are an email assistant. When given email content, analyze it and provide:

1. **Summary:** 3 bullet points of key information
2. **Intent:** Classify as Question, Request, FYI, or Complaint
3. **Suggested Action:** Recommend appropriate response

## Guidelines
- Be concise and actionable
- Identify urgency level (High/Medium/Low)
- Extract any deadlines mentioned
- Note if CC'd recipients need responses

## Output Format
📧 **Email Summary:**
• [Key point 1]
• [Key point 2]
• [Key point 3]

**Sender Intent:** [Classification]
**Urgency:** [Level]
**Suggested Action:** [Specific recommendation]

## Tone
Professional, empathetic, solution-oriented

Example 2: Code Reviewer

You are a senior code reviewer focusing on security, performance, and maintainability.

## Review Criteria

When analyzing code:

1. **Security:** Check for:
   - SQL injection vulnerabilities
   - Cross-site scripting (XSS)
   - Authentication bypasses
   - Exposed secrets or credentials

2. **Performance:** Look for:
   - N+1 query problems
   - Memory leaks
   - Inefficient algorithms
   - Missing database indexes

3. **Code Quality:** Evaluate:
   - Naming conventions
   - Code organization
   - Error handling
   - Test coverage

## Output Format

### 🔴 Critical Issues
[Line X] Description of security or breaking issue
**Fix:** Specific code suggestion

### 🟡 Improvements
[Line Y] Description of non-critical improvement
**Suggestion:** How to optimize

### ✅ Good Practices
Highlight well-written code with brief praise

## Tone
Constructive, educational, specific. Always explain WHY changes are recommended.
Focus on teaching, not criticizing.

Example 3: Customer Support Bot

You are a customer support agent for TechCorp. Your goal is to resolve customer issues quickly and professionally.

## Interaction Flow

1. **Acknowledge** customer concern with empathy
2. **Clarify** ask questions if issue is unclear
3. **Solve** provide step-by-step resolution
4. **Confirm** check if issue is resolved
5. **Follow-up** offer additional assistance

## Knowledge Base

**Company Info:**
- Support hours: Mon-Fri 9am-6pm EST
- Phone: 1-800-TECHCORP
- Email: support@techcorp.com
- Return policy: 30 days for full refund

**Common Issues:**
- Password reset → Direct to /reset-password
- Billing questions → Escalate to finance team
- Technical bugs → Create support ticket

## Escalation Rules

Escalate to supervisor if:
- Customer requests manager
- Issue involves refund >$500
- Customer is angry or threatening
- Technical issue requires engineering

## Tone

Friendly, professional, empathetic. Use:
- "I understand your frustration..."
- "Let me help you with that..."
- "I'm sorry you're experiencing this issue..."

Avoid:
- Technical jargon
- Blame (customer or company)
- Making promises you can't keep

3. Claude Settings

Configure the Claude AI model and behavior parameters. [Screenshot: Claude Settings panel expanded]

Model Selection

Choose the right Claude model for your use case:

Model	Best For	Speed	Cost	Token Limit
claude-opus-4-5	Complex reasoning, coding, analysis	Slow	High	200K
claude-sonnet-4-5	General-purpose, balanced	Medium	Medium	200K
claude-haiku-4-0	Simple tasks, speed-critical	Fast	Low	200K

Selection guide: Use Opus when:

Complex reasoning required (multi-step logic)
Code generation and debugging
Deep analysis and research
Quality is more important than speed

Use Sonnet when:

General-purpose tasks
Balanced speed and quality
Most common use cases
Cost-effectiveness matters

Use Haiku when:

Simple, well-defined tasks
Speed is critical
High-volume operations
Cost minimization important

Temperature (0.0 - 1.0)

Controls response randomness and creativity.

0.0 ──────── 0.5 ──────── 1.0
Deterministic  Balanced  Creative

<-------- Less Random | More Random -------->

Temperature guide: 0.0 - 0.3 (Focused)

Code review and analysis
Data extraction
Factual question answering
Consistent formatting

0.4 - 0.7 (Balanced)

General assistance
Email drafting
Document summarization
Mixed creative/factual tasks

0.8 - 1.0 (Creative)

Creative writing
Brainstorming
Idea generation
Story telling

Examples:

Code Reviewer: 0.2  # Consistent, focused analysis
Email Writer: 0.5   # Balanced, natural language
Story Generator: 0.9 # Creative, varied outputs

Max Tokens

Maximum length of response in tokens (roughly 4 characters per token). Common values:

Tokens	Approx Words	Approx Pages	Use Case
512	~380	0.5	Short summaries
1024	~760	1	Standard responses
2048	~1500	2	Detailed analysis
4096	~3000	4	Long-form content
8192	~6000	8	Comprehensive reports

Selection guide:

Short answers (summaries, quick questions) → 512-1024
Standard responses (email drafts, code reviews) → 1024-2048
Long content (reports, documentation) → 4096-8192

Note: Higher limits increase cost but don’t guarantee longer responses. Agent stops when task complete.

4. Permissions

Control what your agent can access and modify. Three permission levels:

Allow (🟢) - Agent can use without asking
Ask (🟡) - Agent requests permission each time
Deny (🔴) - Agent cannot use at all

[Screenshot: Permissions panel showing allow/ask/deny options]

File System Permissions

read

Read file contents
View file metadata
Safe for most agents

write

Create new files
Modify existing files
⚠️ Use with caution

delete

Remove files permanently
⚠️ Very dangerous - usually deny

list_allowed_directories

Browse folder structure
List files and directories
Safe to allow

Execution Permissions

bash

Run shell commands
Execute scripts
⚠️ Powerful - recommend ask

python / javascript / etc.

Execute code in specific language
⚠️ Can modify system - recommend ask

Network Permissions

network

Make HTTP requests
Access external APIs
⚠️ Can leak data - configure carefully

api_access

Call external services
Database connections
⚠️ Depends on API - review per case

Recommended Configurations

Low-Risk Agent (Read-only)

Allow:
✅ read
✅ list_allowed_directories

Ask:
⚠️ [none]

Deny:
❌ write
❌ delete
❌ bash
❌ network

Medium-Risk Agent (Interactive)

Allow:
✅ read
✅ list_allowed_directories

Ask:
⚠️ write
⚠️ bash

Deny:
❌ delete
❌ network (unless needed)

High-Risk Agent (Full Access)

Allow:
✅ read
✅ write
✅ list_allowed_directories
✅ bash

Ask:
⚠️ delete
⚠️ network

Deny:
❌ [none, or system-critical operations]

5. Permission Modes

Control how your agent handles permission requests during chat. [Screenshot: Permission mode dropdown] Available Modes: default (Recommended for development)

Agent asks for permission on each tool use
User approves/denies in chat interface
Safest option

acceptEdits (Quick editing)

Auto-approve file modifications
Still asks for dangerous operations (delete, execute)
Good for iterative development

bypassPermissions (Advanced)

Run all tools without asking
⚠️ Dangerous - only for trusted workflows
Use in controlled environments only

plan (Planning mode)

Agent shows plan before execution
User reviews full workflow
Proceeds after approval

dontAsk (Silent mode)

No approval notifications
Tools run based on permissions
User not interrupted

Recommendation: Start with default, move to acceptEdits once workflow is tested.

6. Sandbox Mode

Isolate your agent from system-level access. Enabled (✅ Recommended for testing)

Agent runs in isolated environment
Limited file system access
No system-level commands
Safe for experimentation

Disabled (⚠️ Use with caution)

Full system access based on permissions
Can execute any allowed command
Required for some production use cases
⚠️ Review security implications

Excluded Commands (cannot bypass sandbox):

rm -rf        # Recursive deletion
sudo          # Elevated permissions
chmod         # Permission changes
systemctl     # System services

[Screenshot: Sandbox toggle with warning]

Connections

The main agent card connects to all other node types via specialized handles.

Handle Locations

       [🪝 Hooks]
      (top-left)
            ↑
            │
[🧠 Memory] ← MAIN → [🛠️ Skills]
(bottom-left) (center) (right)
            ↓
      [🎭 Sub-agents]
      (bottom)

[🔌 MCPs]
(top-right)

Connection Examples

Connect a Skill

Hover over main card right edge
Drag from right handle (circle appears)
Drop on skill node
Red connection line appears

[GIF: Connecting skill to main agent] Use case: Add File System skill for file operations

Connect Memory

Hover over main card bottom-left area
Drag from bottom-left handle
Drop on memory node
Green connection line appears

Use case: Add knowledge base with company information

Connect Sub-agent

Hover over main card bottom center
Drag from bottom handle
Drop on sub-agent node
Purple connection line appears

Use case: Delegate code review to specialist sub-agent

Connect Hook

Hover over main card top-left
Drag from top-left handle
Drop on hook node
Yellow connection line appears

Use case: Add logging hook for tool call audit trail

Connect MCP

Hover over main card top-right
Drag from top-right handle
Drop on MCP node
Blue connection line appears

Use case: Connect Context7 for documentation lookup

Real-World Examples

Example 1: Customer Support Agent

Use Case: Handle customer inquiries with empathy and accuracy Configuration: Name: Customer Support Bot Description: Assists customers with product questions and issues Icon: 💬 System Prompt:

You are a customer support agent for TechCorp. Your goal is to resolve customer issues quickly and professionally.

[Full prompt from earlier example]

Claude Settings:

Model: claude-sonnet-4-5 (balanced)
Temperature: 0.5 (natural conversation)
Max Tokens: 2048 (detailed responses)

Permissions:

Allow:
✅ read (knowledge base)
✅ list_allowed_directories

Ask:
⚠️ write (create support tickets)

Deny:
❌ bash
❌ delete
❌ network

Permission Mode: default (ask for approvals) Sandbox: Enabled ✅ Connected Nodes:

🧠 Memory → Company KB (policies, FAQs)
🛠️ Skill → Ticket Creator
🔌 MCP → CRM Database (read-only)

Example 2: Code Quality Guardian

Use Case: Review code for bugs, security, and style Configuration: Name: Code Quality Guardian Description: Comprehensive code review for security and best practices Icon: 🛡️ System Prompt:

You are a senior code reviewer focusing on security, performance, and maintainability.

[Full prompt from earlier example]

Claude Settings:

Model: claude-opus-4-5 (best reasoning)
Temperature: 0.2 (consistent analysis)
Max Tokens: 4096 (detailed reviews)

Permissions:

Allow:
✅ read (source code files)
✅ list_allowed_directories

Deny:
❌ write (read-only reviewer)
❌ execute
❌ delete

Permission Mode: acceptEdits (for testing) Sandbox: Enabled ✅ Connected Nodes:

🛠️ Skill → File System (read code)
🧠 Memory → Style Guide
🪝 Hook → PreToolUse (log all file reads)
🎭 Sub-agent → Security Scanner (specialized)

Example 3: Research Assistant

Use Case: Comprehensive research with citation Configuration: Name: Research Assistant Pro Description: Researches topics and generates cited reports Icon: 🔍 System Prompt:

You are a research assistant. When given a topic, you:

1. **Research:** Search multiple sources
2. **Synthesize:** Combine information into coherent narrative
3. **Cite:** Always include source links
4. **Organize:** Use clear sections and headings

## Output Format

# Topic: [Research Topic]

## Executive Summary
[2-3 paragraph overview]

## Detailed Findings

### [Subtopic 1]
[Content with citations[1]]

### [Subtopic 2]
[Content with citations[2]]

## Conclusions
[Key takeaways]

## Sources
[1] [Full citation with URL]
[2] [Full citation with URL]

## Tone
Objective, academic, well-sourced. Avoid speculation without noting it as such.

Claude Settings:

Model: claude-sonnet-4-5 (balanced)
Temperature: 0.4 (mostly factual, some synthesis)
Max Tokens: 8192 (long reports)

Permissions:

Allow:
✅ read
✅ network (web search)
✅ list_allowed_directories

Ask:
⚠️ write (save reports)

Deny:
❌ bash
❌ delete

Permission Mode: acceptEdits (allow writing reports) Sandbox: Disabled ⚠️ (needs network access) Connected Nodes:

🛠️ Skill → Web Search
🛠️ Skill → File System
🧠 Memory → Research Guidelines
🔌 MCP → Context7 (documentation lookup)

Best Practices

System Prompt Design

✅ Do:

Define clear role and objectives
Use hierarchical structure (headings, lists)
Provide explicit output format examples
Set constraints and guidelines
Include error handling instructions
Specify tone and personality

❌ Don’t:

Write overly long prompts (>3000 chars)
Use contradictory instructions
Assume implicit knowledge
Be vague about expectations
Skip output format specification

Model Selection Strategy

Task Complexity:
Simple → Haiku
Medium → Sonnet
Complex → Opus

Speed Priority:
Critical → Haiku
Balanced → Sonnet
Quality → Opus

Cost Priority:
Budget → Haiku
Standard → Sonnet
Premium → Opus

Permission Strategy

Development Phase:

Sandbox: ON
Permission Mode: default (ask everything)
Permissions: Minimal (read-only)

Testing Phase:

Sandbox: ON
Permission Mode: acceptEdits (faster iteration)
Permissions: Moderate (read + ask write)

Production Phase:

Sandbox: OFF (if needed)
Permission Mode: Based on use case
Permissions: Principle of least privilege

Troubleshooting

Agent doesn’t respond or gives errors

Problem: Chat hangs or shows “Agent failed to respond” Solutions:

Check Claude authentication (Settings → Claude Configuration)
Verify model selection is valid
Check permissions allow needed operations
Review system prompt for conflicts
Reduce temperature if outputs are erratic

Agent ignores system prompt

Problem: Agent doesn’t follow instructions or format Solutions:

Lower temperature (try 0.2-0.4)
Add explicit examples in system prompt
Use stronger directives (“You MUST…”, “Always…”, “Never…”)
Simplify instructions (break into smaller steps)
Test with different model (Opus more instruction-following)

Permission errors in chat

Problem: “Permission denied” or tool calls fail Solutions:

Check permissions in agent config match needed operations
Change permission mode to default to see approval requests
Verify sandbox mode isn’t blocking needed operations
Review file/directory paths are within allowed directories

Responses too long or too short

Problem: Agent output length doesn’t match needs Solutions: Too long:

Reduce max tokens
Add length constraint to system prompt (“Keep under 200 words”)
Lower temperature (more focused)

Too short:

Increase max tokens
Request more detail in system prompt (“Provide comprehensive analysis”)
Raise temperature slightly (more expansive)

Next Steps

Learn about other node types:

Skills Node - Add capabilities to your agent
Memory Node - Give your agent persistent knowledge
Sub-agents Node - Delegate to specialist agents

Master the workflow:

Testing Agents - Use chat interface effectively
Exporting Agents - Deploy to production

Ready to add capabilities to your agent?Add Skills → | Add Memory → | Add Sub-agents →

Getting Started

Node Types

AI Tools

​Agent Node (Main Card)

​Overview

​Configuration Sections

​1. Basic Information

​2. System Prompt

​✅ Do:

​❌ Don’t:

​Example System Prompts

​Example 1: Email Summarizer

​Example 2: Code Reviewer

​Example 3: Customer Support Bot

​3. Claude Settings

​Model Selection

​Temperature (0.0 - 1.0)

​Max Tokens

​4. Permissions

​File System Permissions

​Execution Permissions

​Network Permissions

​Recommended Configurations

​5. Permission Modes

​6. Sandbox Mode

​Connections

​Handle Locations

​Connection Examples

​Connect a Skill

​Connect Memory

​Connect Sub-agent

​Connect Hook

​Connect MCP

​Real-World Examples

​Example 1: Customer Support Agent

​Example 2: Code Quality Guardian

​Example 3: Research Assistant

​Best Practices

​System Prompt Design

​Model Selection Strategy

​Permission Strategy

​Troubleshooting

​Agent doesn’t respond or gives errors

​Agent ignores system prompt

​Permission errors in chat

​Responses too long or too short

​Next Steps

Agent Node (Main Card)

Overview

Configuration Sections

1. Basic Information

2. System Prompt

✅ Do:

❌ Don’t:

Example System Prompts

Example 1: Email Summarizer

Example 2: Code Reviewer

Example 3: Customer Support Bot

3. Claude Settings

Model Selection

Temperature (0.0 - 1.0)

Max Tokens

4. Permissions

File System Permissions

Execution Permissions

Network Permissions

Recommended Configurations

5. Permission Modes

6. Sandbox Mode

Connections

Handle Locations

Connection Examples

Connect a Skill

Connect Memory

Connect Sub-agent

Connect Hook

Connect MCP

Real-World Examples

Example 1: Customer Support Agent

Example 2: Code Quality Guardian

Example 3: Research Assistant

Best Practices

System Prompt Design

Model Selection Strategy

Permission Strategy

Troubleshooting

Agent doesn’t respond or gives errors

Agent ignores system prompt

Permission errors in chat

Responses too long or too short

Next Steps