Skip to main content

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:
Description
  • Brief summary of agent’s purpose
  • Internal documentation (not sent to Claude)
  • Shows on dashboard cards
Examples:
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
2. Use structured instructions
3. Define output format explicitly
4. Set tone and personality
5. Specify constraints

❌ Don’t:

1. Vague instructions
2. Conflicting directives
3. Overly long prompts
4. Assume implicit knowledge

Example System Prompts

Example 1: Email Summarizer


Example 2: Code Reviewer


Example 3: Customer Support Bot


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: 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.
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:

Max Tokens

Maximum length of response in tokens (roughly 4 characters per token). Common values: 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
Low-Risk Agent (Read-only)
Medium-Risk Agent (Interactive)
High-Risk Agent (Full Access)

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):
[Screenshot: Sandbox toggle with warning]

Connections

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

Handle Locations

Connection Examples

Connect a Skill

  1. Hover over main card right edge
  2. Drag from right handle (circle appears)
  3. Drop on skill node
  4. Red connection line appears
[GIF: Connecting skill to main agent] Use case: Add File System skill for file operations

Connect Memory

  1. Hover over main card bottom-left area
  2. Drag from bottom-left handle
  3. Drop on memory node
  4. Green connection line appears
Use case: Add knowledge base with company information

Connect Sub-agent

  1. Hover over main card bottom center
  2. Drag from bottom handle
  3. Drop on sub-agent node
  4. Purple connection line appears
Use case: Delegate code review to specialist sub-agent

Connect Hook

  1. Hover over main card top-left
  2. Drag from top-left handle
  3. Drop on hook node
  4. Yellow connection line appears
Use case: Add logging hook for tool call audit trail

Connect MCP

  1. Hover over main card top-right
  2. Drag from top-right handle
  3. Drop on MCP node
  4. 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:
Claude Settings:
  • Model: claude-sonnet-4-5 (balanced)
  • Temperature: 0.5 (natural conversation)
  • Max Tokens: 2048 (detailed responses)
Permissions:
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:
Claude Settings:
  • Model: claude-opus-4-5 (best reasoning)
  • Temperature: 0.2 (consistent analysis)
  • Max Tokens: 4096 (detailed reviews)
Permissions:
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:
Claude Settings:
  • Model: claude-sonnet-4-5 (balanced)
  • Temperature: 0.4 (mostly factual, some synthesis)
  • Max Tokens: 8192 (long reports)
Permissions:
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:
❌ Don’t:

Model Selection Strategy


Permission Strategy

Development Phase:
Testing Phase:
Production Phase:

Troubleshooting

Agent doesn’t respond or gives errors

Problem: Chat hangs or shows “Agent failed to respond” Solutions:
  1. Check Claude authentication (Settings → Claude Configuration)
  2. Verify model selection is valid
  3. Check permissions allow needed operations
  4. Review system prompt for conflicts
  5. Reduce temperature if outputs are erratic

Agent ignores system prompt

Problem: Agent doesn’t follow instructions or format Solutions:
  1. Lower temperature (try 0.2-0.4)
  2. Add explicit examples in system prompt
  3. Use stronger directives (“You MUST…”, “Always…”, “Never…”)
  4. Simplify instructions (break into smaller steps)
  5. Test with different model (Opus more instruction-following)

Permission errors in chat

Problem: “Permission denied” or tool calls fail Solutions:
  1. Check permissions in agent config match needed operations
  2. Change permission mode to default to see approval requests
  3. Verify sandbox mode isn’t blocking needed operations
  4. 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: Master the workflow:
Ready to add capabilities to your agent?Add Skills → | Add Memory → | Add Sub-agents →