Skip to content

Commit 2a8fd05

Browse files
committedJun 3, 2025·
updated tools, agents, sdk doc
1 parent 28620f9 commit 2a8fd05

20 files changed

+6806
-164
lines changed
 

‎docs/developer/agents/1_agentIntroduction.md

Lines changed: 0 additions & 31 deletions
This file was deleted.

‎docs/developer/agents/2_usingagents/2_quickstart.md

Lines changed: 0 additions & 3 deletions
This file was deleted.
Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
---
2+
sidebar_position: 1
3+
sidebar_label: Introduction
4+
---
5+
6+
# Agent Introduction
7+
8+
Codebolt is an extremely powerful platform for AI-driven code editing and generation. The core strength of Codebolt lies in its agent-based architecture, where specialized AI agents handle different aspects of software development, from code generation to testing and deployment.
9+
10+
## What is a Codebolt Agent?
11+
12+
A Codebolt Agent is a custom AI-powered application that connects to the Codebolt platform to execute specific development tasks. Think of agents as specialized developers with unique skills - one might excel at React component generation, another at API development, and yet another at testing automation.
13+
14+
### Key Characteristics
15+
16+
- **Specialized**: Each agent focuses on specific development tasks or domains
17+
- **Autonomous**: Agents can make decisions and take actions using LLM reasoning
18+
- **Connected**: Agents integrate seamlessly with the Codebolt application
19+
- **Extensible**: Agents can use tools and call other agents for complex workflows
20+
- **Reusable**: Once created, agents can be shared and used across projects
21+
22+
## How Agents Work
23+
24+
Codebolt agents operate through an agentic process flow that combines:
25+
26+
1. **User Intent Understanding**: Parsing and interpreting user requests
27+
2. **Task Planning**: Breaking down complex tasks into actionable steps
28+
3. **Tool Utilization**: Using available tools and APIs to accomplish tasks
29+
4. **Code Manipulation**: Reading, writing, and modifying code files
30+
5. **Decision Making**: Using LLM reasoning to make intelligent choices
31+
6. **Result Delivery**: Providing feedback and results to users
32+
33+
## Agent Architecture
34+
35+
```mermaid
36+
graph TB
37+
subgraph "Codebolt Application"
38+
A[Codebolt Editor]
39+
B[Agent Orchestrator]
40+
C[Universal Agent Router]
41+
D[Tool Registry]
42+
E[File System]
43+
end
44+
45+
subgraph "Agent Runtime"
46+
F[Custom Agent]
47+
G[CodeboltJS Library]
48+
H[Agent Logic]
49+
I[System Prompts]
50+
J[Task Instructions]
51+
end
52+
53+
subgraph "External Services"
54+
K[LLM Providers]
55+
L[External APIs]
56+
M[Tool Services]
57+
end
58+
59+
A --> B
60+
B --> C
61+
C --> F
62+
F --> G
63+
G --> H
64+
H --> I
65+
H --> J
66+
67+
G <--> A
68+
G <--> D
69+
G <--> E
70+
71+
H --> K
72+
H --> L
73+
H --> M
74+
75+
F --> B
76+
```
77+
78+
## Agent Connection Flow
79+
80+
Codebolt agents connect to the platform using the **CodeboltJS library**, which provides a comprehensive set of functions for:
81+
82+
### 1. Communication Layer
83+
```javascript
84+
// WebSocket connection for real-time communication
85+
codebolt.chat.onActionMessage().on("userMessage", async (req, response) => {
86+
// Handle user messages and respond
87+
});
88+
```
89+
90+
### 2. Tool Integration
91+
```javascript
92+
// Access to platform tools and external services
93+
const tools = await codebolt.tools.listToolsFromToolBoxes(["codebolt", "custom"]);
94+
```
95+
96+
### 3. File System Access
97+
```javascript
98+
// Read, write, and manipulate project files
99+
const fileContent = await codebolt.fs.readFile("./src/component.js");
100+
await codebolt.fs.writeFile("./src/newComponent.js", generatedCode);
101+
```
102+
103+
### 4. LLM Integration
104+
```javascript
105+
// Interact with various LLM providers
106+
const response = await codebolt.llm.chat(messages, tools);
107+
```
108+
109+
## Agent Types and Use Cases
110+
111+
### 1. **Code Generation Agents**
112+
- Generate React components, API endpoints, database models
113+
- Create boilerplate code and project structures
114+
- Implement design patterns and best practices
115+
116+
### 2. **Testing Agents**
117+
- Write unit tests, integration tests, and end-to-end tests
118+
- Generate test data and mock objects
119+
- Analyze code coverage and suggest improvements
120+
121+
### 3. **Deployment Agents**
122+
- Deploy applications to various platforms (Vercel, AWS, etc.)
123+
- Configure CI/CD pipelines
124+
- Manage environment variables and secrets
125+
126+
### 4. **Code Review Agents**
127+
- Analyze code quality and suggest improvements
128+
- Check for security vulnerabilities
129+
- Ensure coding standards compliance
130+
131+
### 5. **Documentation Agents**
132+
- Generate API documentation
133+
- Create README files and user guides
134+
- Maintain code comments and inline documentation
135+
136+
## Agent Lifecycle
137+
138+
### Development Phase
139+
1. **Create**: Use CLI to scaffold agent structure
140+
2. **Configure**: Define SDLC steps, actions, and routing
141+
3. **Implement**: Write agent logic using CodeboltJS
142+
4. **Test**: Run locally and test with Codebolt application
143+
144+
### Deployment Phase
145+
1. **Publish**: Upload to Codebolt registry
146+
2. **Share**: Make available to community or team
147+
3. **Version**: Manage updates and backward compatibility
148+
149+
### Runtime Phase
150+
1. **Discovery**: Users find agents through registry
151+
2. **Installation**: Clone or install agents in projects
152+
3. **Execution**: Agents handle user requests and tasks
153+
4. **Monitoring**: Track performance and usage
154+
155+
## Agent Communication Protocol
156+
157+
Agents communicate with Codebolt through a structured protocol:
158+
159+
```javascript
160+
// Message Structure
161+
{
162+
type: "userMessage",
163+
content: "Generate a React component for user profile",
164+
context: {
165+
projectPath: "/path/to/project",
166+
currentFile: "src/App.js",
167+
selectedText: "...",
168+
metadata: {...}
169+
}
170+
}
171+
172+
// Response Structure
173+
{
174+
success: true,
175+
message: "Created UserProfile component successfully",
176+
actions: [
177+
{
178+
type: "fileCreate",
179+
path: "src/components/UserProfile.js",
180+
content: "..."
181+
}
182+
]
183+
}
184+
```
185+
186+
## Benefits of Agent-Based Architecture
187+
188+
### For Developers
189+
- **Specialization**: Focus on specific domains and use cases
190+
- **Reusability**: Create once, use across multiple projects
191+
- **Collaboration**: Share agents with team and community
192+
- **Extensibility**: Build on existing agents and tools
193+
194+
### For Users
195+
- **Efficiency**: Automated complex development tasks
196+
- **Consistency**: Standardized approaches across projects
197+
- **Learning**: Discover new patterns and best practices
198+
- **Flexibility**: Choose the right agent for each task
199+
200+
### For Organizations
201+
- **Standardization**: Enforce coding standards and practices
202+
- **Knowledge Sharing**: Capture and distribute expertise
203+
- **Productivity**: Accelerate development workflows
204+
- **Quality**: Consistent, tested approaches to common tasks
205+
206+
## Getting Started
207+
208+
Ready to create your first agent? Here's what you need:
209+
210+
1. **Prerequisites**: Node.js, Codebolt CLI, and basic JavaScript knowledge
211+
2. **Quick Start**: Follow our [QuickStart Guide](./quickstart.md) for a 10-minute setup
212+
3. **Deep Dive**: Explore [Agent Architecture](./1_agentarchitecture.md) for detailed concepts
213+
4. **Examples**: Check out [Custom Agents](./3_customagents.md) for real-world examples
214+
215+
## Agent Ecosystem
216+
217+
The Codebolt agent ecosystem includes:
218+
219+
- **Official Agents**: Maintained by the Codebolt team
220+
- **Community Agents**: Created and shared by developers
221+
- **Private Agents**: Custom agents for specific organizations
222+
- **Tool Integration**: Agents that wrap external services and APIs
223+
224+
## Next Steps
225+
226+
- **[QuickStart Guide](./quickstart.md)** - Create your first agent in 10 minutes
227+
- **[Agent Architecture](./1_agentarchitecture.md)** - Understand the technical details
228+
- **[Using Agents](./2_usingagents.md)** - Learn how to effectively use agents
229+
- **[Custom Agents](./3_customagents.md)** - Build specialized agents for your needs
230+
231+
---
232+
233+
Codebolt agents represent the future of AI-assisted development - intelligent, specialized, and collaborative tools that amplify human creativity and productivity in software development.
234+
235+
236+

‎docs/developer/agents/multi-agent.md

Whitespace-only changes.

‎docs/developer/agents/quickstart.md

Lines changed: 334 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,334 @@
1+
---
2+
sidebar_position: 2
3+
sidebar_label: QuickStart
4+
---
5+
6+
# QuickStart
7+
8+
This guide will walk you through creating your first Codebolt agent in under 10 minutes. For detailed explanations, see the [complete documentation](./1_agentarchitecture.md).
9+
10+
## Prerequisites
11+
12+
- Node.js 14+ installed
13+
- Codebolt CLI installed: `npm install -g codebolt-cli`
14+
- Codebolt account (sign up at [portal.codebolt.ai](https://portal.codebolt.ai))
15+
- Basic understanding of JavaScript/TypeScript
16+
17+
## Step 1: Login and Create Agent
18+
19+
Go to the main directory of your project and run the following commands:
20+
21+
```bash
22+
# Login to Codebolt
23+
npx codebolt-cli login
24+
25+
# Create a new agent
26+
npx codebolt-cli createagent --name "Hello World Agent"
27+
```
28+
29+
This will create a new agent directory in the `.codeboltAgents` directory and start an interactive setup process.
30+
31+
```bash
32+
# Navigate to agent directory
33+
cd .codeboltAgents/hello-world-agent
34+
```
35+
36+
## Step 2: Configure Your Agent
37+
38+
During the interactive setup, you'll be prompted for:
39+
40+
### Basic Information
41+
- **Agent Name**: "Hello World Agent"
42+
- **Description**: "A simple greeting agent for learning Codebolt"
43+
- **Tags**: "hello, demo, learning"
44+
- **Unique ID**: "hello-world-agent" (auto-generated)
45+
46+
### Agent Routing Configuration
47+
- **Works on blank code**: Yes
48+
- **Works on existing code**: Yes
49+
- **Supported languages**: JavaScript, TypeScript
50+
- **Supported frameworks**: Node.js, React
51+
52+
### SDLC Steps Managed
53+
Choose what development steps your agent handles:
54+
- **Code Generation**: "Generate a greeting function", "Create a hello world component"
55+
- **Testing**: "Test the greeting functionality"
56+
57+
### Actions
58+
Define shortcuts users can invoke with `\` commands:
59+
- **Action Name**: "greet"
60+
- **Description**: "Generate a personalized greeting"
61+
- **Action Prompt**: "Create a greeting for the user"
62+
63+
## Step 3: Understand Agent Structure
64+
65+
Your agent will have this structure:
66+
67+
```
68+
.codeboltAgents/hello-world-agent/
69+
├── codeboltagent.yaml # Agent configuration
70+
├── agent.yaml # System prompts and behavior
71+
├── task.yaml # Task execution templates
72+
├── index.js # Main agent logic
73+
├── package.json # Dependencies
74+
└── webpack.config.js # Build configuration
75+
```
76+
77+
## Step 4: Customize Agent Behavior
78+
79+
### Edit System Prompt (`agent.yaml`)
80+
81+
```yaml
82+
system_prompt: |
83+
You are a friendly greeting agent. Your job is to:
84+
1. Generate personalized greetings
85+
2. Help users learn about Codebolt
86+
3. Provide helpful responses about agent development
87+
88+
Always be polite, helpful, and encouraging.
89+
90+
tools_instruction: |
91+
Use the available tools to help users with their requests.
92+
When greeting, make it personal and warm.
93+
```
94+
95+
### Update Agent Logic (`index.js`)
96+
97+
The basic structure is already provided, but you can customize it:
98+
99+
```javascript
100+
const codebolt = require('@codebolt/codeboltjs').default;
101+
const { UserMessage, SystemPrompt, TaskInstruction, Agent } = require("@codebolt/codeboltjs/utils");
102+
103+
codebolt.chat.onActionMessage().on("userMessage", async (req, response) => {
104+
try {
105+
// Create user message from request
106+
const userMessage = new UserMessage(req.message);
107+
108+
// Load system prompt from agent.yaml
109+
const systemPrompt = new SystemPrompt("./agent.yaml", "system_prompt");
110+
111+
// Get available tools
112+
const agentTools = await codebolt.tools.listToolsFromToolBoxes(["codebolt"]);
113+
114+
// Create task instruction
115+
const task = new TaskInstruction(agentTools, userMessage, "./task.yaml", "main_task");
116+
117+
// Initialize agent
118+
const agent = new Agent(agentTools, systemPrompt);
119+
120+
// Run the agent
121+
const { message, success, error } = await agent.run(task);
122+
123+
// Send response
124+
response(message ? message : error);
125+
126+
} catch (error) {
127+
console.log("Agent error:", error);
128+
response("Sorry, I encountered an error processing your request.");
129+
}
130+
});
131+
```
132+
133+
## Step 5: Test Your Agent Locally
134+
135+
```bash
136+
# Install dependencies
137+
npm install
138+
139+
# Start the agent locally
140+
npx codebolt-cli startagent
141+
142+
# The agent will start on localhost with socket connection
143+
# You should see: "Agent process started..."
144+
```
145+
146+
## Step 6: Test in Codebolt Application
147+
148+
1. **Open Codebolt Application** and navigate to your project
149+
2. **Enable the Agent**: Go to Agent settings and enable your local agent
150+
3. **Test Basic Functionality**:
151+
```
152+
User: Hello, can you greet me?
153+
Agent: Hello! Welcome to Codebolt. I'm your friendly greeting agent, ready to help you learn and build amazing things!
154+
```
155+
156+
4. **Test Action Commands**:
157+
```
158+
User: \greet
159+
Agent: [Executes the greet action you defined]
160+
```
161+
162+
## Step 7: Publish Your Agent
163+
164+
Once your agent works locally, publish it to the registry:
165+
166+
```bash
167+
# Publish to registry
168+
npx codebolt-cli publishagent
169+
170+
# Follow the prompts:
171+
# - GitHub URL (optional)
172+
# - Category: "Utility"
173+
# - Make it public: Yes
174+
```
175+
176+
## Step 8: Use Your Published Agent
177+
178+
```bash
179+
# Clone your published agent in another project
180+
npx codebolt-cli cloneagent hello-world-agent
181+
182+
# Or others can clone it using your unique ID
183+
npx codebolt-cli cloneagent hello-world-agent ./my-project
184+
```
185+
186+
## Quick Commands Reference
187+
188+
```bash
189+
# Agent Management
190+
npx codebolt-cli createagent # Create new agent
191+
npx codebolt-cli startagent [dir] # Start agent locally
192+
npx codebolt-cli publishagent [dir] # Publish to registry
193+
npx codebolt-cli pullagent [dir] # Pull latest config
194+
195+
# Registry Operations
196+
npx codebolt-cli listagents # List your agents
197+
npx codebolt-cli cloneagent <id> [dir] # Clone agent
198+
```
199+
200+
## Example Agent Configurations
201+
202+
### Simple Code Generator Agent
203+
204+
```yaml
205+
# codeboltagent.yaml
206+
title: "Code Generator Agent"
207+
description: "Generates boilerplate code for common patterns"
208+
metadata:
209+
sdlc_steps_managed:
210+
- name: codegeneration
211+
example_instructions:
212+
- "Generate a React component"
213+
- "Create an API endpoint"
214+
- "Build a database model"
215+
```
216+
217+
### Testing Assistant Agent
218+
219+
```yaml
220+
# codeboltagent.yaml
221+
title: "Testing Assistant"
222+
description: "Helps write and run tests"
223+
metadata:
224+
sdlc_steps_managed:
225+
- name: testing
226+
example_instructions:
227+
- "Write unit tests for this function"
228+
- "Create integration tests"
229+
- "Generate test data"
230+
```
231+
232+
### Deployment Helper Agent
233+
234+
```yaml
235+
# codeboltagent.yaml
236+
title: "Deployment Helper"
237+
description: "Assists with deployment tasks"
238+
metadata:
239+
sdlc_steps_managed:
240+
- name: deployment
241+
example_instructions:
242+
- "Deploy to Vercel"
243+
- "Set up CI/CD pipeline"
244+
- "Configure environment variables"
245+
```
246+
247+
## Agent Development Tips
248+
249+
### 1. Start Simple
250+
Begin with basic functionality and gradually add complexity:
251+
252+
```javascript
253+
// Simple greeting logic
254+
if (userMessage.content.toLowerCase().includes('hello')) {
255+
return "Hello! How can I help you today?";
256+
}
257+
```
258+
259+
### 2. Use Tools Effectively
260+
Leverage available tools for enhanced functionality:
261+
262+
```javascript
263+
// Get available tools
264+
const tools = await codebolt.tools.listToolsFromToolBoxes(["codebolt", "custom"]);
265+
266+
// Use specific tools in your agent logic
267+
const fileTools = tools.filter(tool => tool.name.includes('file'));
268+
```
269+
270+
### 3. Handle Errors Gracefully
271+
Always provide helpful error messages:
272+
273+
```javascript
274+
try {
275+
const result = await agent.run(task);
276+
return result.message;
277+
} catch (error) {
278+
return "I encountered an issue. Please try rephrasing your request.";
279+
}
280+
```
281+
282+
## Next Steps
283+
284+
Now that you've created your first agent, explore:
285+
286+
- **[Agent Architecture](./1_agentarchitecture.md)** - Deep dive into agent concepts
287+
- **[Using Agents](./2_usingagents.md)** - Advanced usage patterns
288+
- **[Custom Agents](./3_customagents.md)** - Building specialized agents
289+
- **[Tools Integration](../tools/quickstart.md)** - Add tools to your agents
290+
291+
## Troubleshooting
292+
293+
**Agent not starting?**
294+
```bash
295+
# Check if dependencies are installed
296+
npm install
297+
298+
# Verify configuration
299+
cat codeboltagent.yaml
300+
301+
# Check for syntax errors
302+
npm run build
303+
```
304+
305+
**Agent not responding in app?**
306+
```bash
307+
# Ensure agent is running
308+
npx codebolt-cli startagent
309+
310+
# Check agent is enabled in Codebolt Application
311+
# Verify socket connection (default port 12345)
312+
```
313+
314+
**Publishing failed?**
315+
```bash
316+
# Check authentication
317+
npx codebolt-cli login
318+
319+
# Verify unique ID is not taken
320+
npx codebolt-cli listagents
321+
```
322+
323+
**Need help?**
324+
```bash
325+
# Get help
326+
npx codebolt-cli --help
327+
328+
# Check agent status
329+
ps aux | grep node
330+
```
331+
332+
---
333+
334+
🎉 **Congratulations!** You've created, tested, and published your first Codebolt agent. Start building more sophisticated agents by exploring the detailed documentation and integrating tools for enhanced functionality.

‎docs/developer/templates/overview.md

Whitespace-only changes.

‎docs/developer/tools/create_tool.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -610,7 +610,7 @@ parameters:
610610
611611
## Next Steps
612612
613-
- [Test Your Tool Locally](./3_testlocalmcp.md) - Learn advanced testing techniques
614-
- [Publish Your Tool](./4_publish_tool.md) - Share your tool with the community
615-
- [Tool Registry](./5_tool_registry.md) - Discover and use existing tools
616-
- [Advanced Patterns](./6_advanced_patterns.md) - Learn advanced tool development patterns
613+
- [Test Your Tool Locally](./testlocalmcp.md) - Learn advanced testing techniques
614+
- [Publish Your Tool](./publish_tool.md) - Share your tool with the community
615+
- [Tool Registry](./tool_registry.md) - Discover and use existing tools
616+
- [Advanced Patterns](./advanced_patterns.md) - Learn advanced tool development patterns

‎docs/developer/tools/examples.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
sidebar_position: 7
3+
---
4+
# Examples
5+
6+
## Example Use Cases
7+
8+
### API Integration Tool
9+
```bash
10+
npx codebolt-cli createtool --name "Weather Tool" --id "weather-tool"
11+
# Add API key parameter and fetch weather data
12+
```
13+
14+
### File Processing Tool
15+
```bash
16+
npx codebolt-cli createtool --name "CSV Parser" --id "csv-parser"
17+
# Add file reading and CSV parsing logic
18+
```
19+
20+
### Data Transformation Tool
21+
```bash
22+
codebolt-cli createtool --name "JSON Formatter" --id "json-formatter"
23+
# Add JSON validation and formatting functions
24+
```

‎docs/developer/tools/quickstart.md

Lines changed: 30 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -121,15 +121,26 @@ npx codebolt-cli inspecttool ./index.js
121121

122122
## Step 5: Test Your Tool in Codebolt Application
123123

124-
Open the Codebolt Application and open the current project.
124+
- Open the Codebolt Application and open the current project.
125+
- Make Sure the [Tool is enabled for the Current Agent](../cli/agents.md#enable-tool).
126+
- In the Chat, ask the AI Agent with the following message:
127+
```
128+
User: Ask Greet Hello World tool to greet Alex.
129+
```
130+
The AI agent should respond with
131+
```
132+
Agent: Hello, Alex!
133+
```
125134

126135

127136

128137
## Step 6: Publish Your Tool
129138

139+
Publish the tool to the Codebolt Registry. This will make the tool available to other users or agents.
140+
130141
```bash
131142
# Publish to registry
132-
codebolt-cli publishtool
143+
npx codebolt-cli publishtool
133144

134145
# Follow the prompts:
135146
# - GitHub URL (optional)
@@ -140,49 +151,37 @@ codebolt-cli publishtool
140151

141152
## Step 7: Use Your Tool
142153

154+
Now you can use the tool in other projects from the registry.
155+
143156
```bash
144157
# Install your published tool
145-
codebolt-cli installtool hello-world-tool
158+
npx codebolt-cli installtool hello-world-tool
146159

147160
# Use in another project
148-
codebolt-cli runtool greet hello-world-tool
161+
npx codebolt-cli runtool greet hello-world-tool
149162
```
150163

164+
---
165+
166+
🎉 **Congratulations!** You've created, tested, and published your first Codebolt tool. Start building more complex tools by exploring the detailed documentation.
167+
151168
## Quick Commands Reference
152169

153170
```bash
154171
# Tool Management
155-
codebolt-cli createtool # Create new tool
156-
codebolt-cli runtool <function> <file> # Test tool function
157-
codebolt-cli inspecttool <file> # Debug tool interactively
158-
codebolt-cli publishtool # Publish to registry
172+
npx codebolt-cli createtool # Create new tool
173+
npx codebolt-cli runtool <function> <file> # Test tool function
174+
npx codebolt-cli inspecttool <file> # Debug tool interactively
175+
npx codebolt-cli publishtool # Publish to registry
159176

160177
# Registry Operations
161-
codebolt-cli searchtools <query> # Search tools
162-
codebolt-cli installtool <tool-name> # Install tool
163-
codebolt-cli listtools --installed # List installed tools
164-
codebolt-cli updatetool <tool-name> # Update tool
165-
```
166-
167-
## Example Use Cases
168-
169-
### API Integration Tool
170-
```bash
171-
codebolt-cli createtool --name "Weather Tool" --id "weather-tool"
172-
# Add API key parameter and fetch weather data
178+
npx codebolt-cli searchtools <query> # Search tools
179+
npx codebolt-cli installtool <tool-name> # Install tool
180+
npx codebolt-cli listtools --installed # List installed tools
181+
npx codebolt-cli updatetool <tool-name> # Update tool
173182
```
174183

175-
### File Processing Tool
176-
```bash
177-
codebolt-cli createtool --name "CSV Parser" --id "csv-parser"
178-
# Add file reading and CSV parsing logic
179-
```
180184

181-
### Data Transformation Tool
182-
```bash
183-
codebolt-cli createtool --name "JSON Formatter" --id "json-formatter"
184-
# Add JSON validation and formatting functions
185-
```
186185

187186
## Next Steps
188187

@@ -192,39 +191,10 @@ Now that you've created your first tool, explore:
192191
- **[Testing Guide](./testlocalmcp.md)** - Comprehensive testing strategies
193192
- **[Publishing Guide](./publish_tool.md)** - Advanced publishing features
194193
- **[Tool Registry](./tool_registry.md)** - Discover and manage tools
194+
- **[Examples](./examples.md)** - Example use cases
195195

196-
## Troubleshooting
197-
198-
**Tool not working?**
199-
```bash
200-
# Check configuration
201-
cat codebolttool.yaml
202-
203-
# Validate tool
204-
codebolt-cli runtool greet ./index.js
205-
```
206-
207-
**Publishing failed?**
208-
```bash
209-
# Check authentication
210-
codebolt-cli whoami
211-
212-
# Verify unique name
213-
codebolt-cli searchtools hello-world-tool
214-
```
215-
216-
**Need help?**
217-
```bash
218-
# Get help
219-
codebolt-cli help
220-
221-
# Check tool status
222-
codebolt-cli toolstatus hello-world-tool
223-
```
224196

225-
---
226197

227-
🎉 **Congratulations!** You've created, tested, and published your first Codebolt tool. Start building more complex tools by exploring the detailed documentation.
228198

229199

230200

‎docs/developer/tools/troubleshoot.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
sidebar_position: 8
3+
sidebar_label: Troubleshooting
4+
---
5+
# Troubleshooting
6+
7+
## Troubleshooting
8+
9+
**Tool not working?**
10+
```bash
11+
# Check configuration
12+
cat codebolttool.yaml
13+
14+
# Validate tool
15+
codebolt-cli runtool greet ./index.js
16+
```
17+
18+
**Publishing failed?**
19+
```bash
20+
# Check authentication
21+
codebolt-cli whoami
22+
23+
# Verify unique name
24+
codebolt-cli searchtools hello-world-tool
25+
```
26+
27+
**Need help?**
28+
```bash
29+
# Get help
30+
codebolt-cli help
31+
32+
# Check tool status
33+
codebolt-cli toolstatus hello-world-tool
34+
```

‎docs/developer/typescriptSdk/agent-framework.md

Lines changed: 704 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/developer/typescriptSdk/api-reference.md

Lines changed: 788 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/developer/typescriptSdk/core-modules.md

Lines changed: 656 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/developer/typescriptSdk/examples.md

Lines changed: 936 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/developer/typescriptSdk/installation.md

Lines changed: 440 additions & 0 deletions
Large diffs are not rendered by default.
Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
---
2+
sidebar_position: 1
3+
sidebar_label: Overview
4+
---
5+
6+
# CodeboltJS TypeScript SDK
7+
8+
The CodeboltJS TypeScript SDK (`@codebolt/codeboltjs`) is a comprehensive library that enables developers to create powerful AI agents that integrate seamlessly with the Codebolt platform. This SDK provides a unified interface to interact with various platform capabilities including file system operations, LLM interactions, terminal commands, browser automation, and much more.
9+
10+
## What is CodeboltJS?
11+
12+
CodeboltJS is the core library that powers Codebolt agents. It provides:
13+
14+
- **WebSocket Communication**: Real-time bidirectional communication with the Codebolt application
15+
- **Modular Architecture**: 20+ specialized modules for different functionalities
16+
- **Type Safety**: Full TypeScript support with comprehensive type definitions
17+
- **Tool Integration**: Built-in support for MCP (Model Context Protocol) tools
18+
- **Agent Framework**: High-level Agent class for building sophisticated AI workflows
19+
20+
## Key Features
21+
22+
### 🔧 **Comprehensive Module System**
23+
- **File System**: Read, write, create, delete files and folders
24+
- **Terminal**: Execute commands with streaming output support
25+
- **Browser**: Automate web interactions and scraping
26+
- **Git**: Complete Git operations integration
27+
- **LLM**: Multi-provider language model interactions
28+
- **Tools**: MCP-compatible tool discovery and execution
29+
- **Chat**: Real-time communication with users
30+
- **And 15+ more specialized modules**
31+
32+
### 🤖 **Agent Framework**
33+
- High-level Agent class for complex workflows
34+
- Tool calling and execution management
35+
- Conversation history management
36+
- Task completion detection
37+
- Sub-agent orchestration
38+
39+
### 🔌 **Platform Integration**
40+
- Seamless integration with Codebolt application
41+
- Real-time file system synchronization
42+
- User interaction capabilities
43+
- Progress tracking and notifications
44+
45+
## Installation
46+
47+
### For Agent Development
48+
49+
```bash
50+
# Install the SDK in your agent project
51+
npm install @codebolt/codeboltjs
52+
53+
# Or using yarn
54+
yarn add @codebolt/codeboltjs
55+
```
56+
57+
### For CLI-based Development
58+
59+
```bash
60+
# Create a new agent using Codebolt CLI
61+
npx codebolt-cli createagent
62+
63+
# The SDK is automatically included in the generated template
64+
```
65+
66+
## Quick Start
67+
68+
### Basic Agent Structure
69+
70+
```typescript
71+
import codebolt from '@codebolt/codeboltjs';
72+
73+
// Wait for WebSocket connection
74+
await codebolt.waitForConnection();
75+
76+
// Set up message handler
77+
codebolt.onMessage(async (userMessage) => {
78+
// Handle user requests
79+
const response = await processUserRequest(userMessage);
80+
return response;
81+
});
82+
83+
async function processUserRequest(message: any) {
84+
// Read project files
85+
const files = await codebolt.fs.listFile('./', true);
86+
87+
// Execute terminal commands
88+
const result = await codebolt.terminal.executeCommand('npm test');
89+
90+
// Interact with LLM
91+
const llmResponse = await codebolt.llm.inference(
92+
'Analyze this code and suggest improvements',
93+
'code-reviewer'
94+
);
95+
96+
return `Task completed: ${llmResponse.message}`;
97+
}
98+
```
99+
100+
### Using the Agent Framework
101+
102+
```typescript
103+
import { Agent, SystemPrompt, TaskInstruction } from '@codebolt/codeboltjs';
104+
105+
// Create system prompt
106+
const systemPrompt = new SystemPrompt(`
107+
You are a React development expert. Help users create and modify React components.
108+
Always follow best practices and modern React patterns.
109+
`);
110+
111+
// Initialize agent with tools
112+
const agent = new Agent([], systemPrompt, 10);
113+
114+
// Create task instruction
115+
const task = new TaskInstruction(userMessage);
116+
117+
// Run the agent
118+
const result = await agent.run(task);
119+
```
120+
121+
## SDK Architecture
122+
123+
```mermaid
124+
graph TB
125+
subgraph "CodeboltJS SDK"
126+
A[Main Codebolt Class]
127+
B[WebSocket Core]
128+
C[Message Manager]
129+
130+
subgraph "Core Modules"
131+
D[File System]
132+
E[Terminal]
133+
F[Browser]
134+
G[Git]
135+
H[LLM]
136+
I[Chat]
137+
J[Tools]
138+
end
139+
140+
subgraph "Utility Modules"
141+
K[Code Utils]
142+
L[Search]
143+
M[Crawler]
144+
N[Vector DB]
145+
O[Debug]
146+
end
147+
148+
subgraph "Agent Framework"
149+
P[Agent Class]
150+
Q[System Prompt]
151+
R[Task Instruction]
152+
end
153+
end
154+
155+
subgraph "Codebolt Platform"
156+
S[Codebolt Application]
157+
T[File System]
158+
U[Terminal]
159+
V[Browser Engine]
160+
W[Tool Registry]
161+
end
162+
163+
A --> B
164+
B --> C
165+
C --> D
166+
C --> E
167+
C --> F
168+
C --> G
169+
C --> H
170+
C --> I
171+
C --> J
172+
173+
A --> K
174+
A --> L
175+
A --> M
176+
A --> N
177+
A --> O
178+
179+
P --> A
180+
Q --> P
181+
R --> P
182+
183+
B <--> S
184+
D <--> T
185+
E <--> U
186+
F <--> V
187+
J <--> W
188+
```
189+
190+
## Available Modules
191+
192+
| Module | Description | Key Functions |
193+
|--------|-------------|---------------|
194+
| **fs** | File system operations | `readFile`, `writeFile`, `createFile`, `listFile` |
195+
| **terminal** | Command execution | `executeCommand`, `executeCommandWithStream` |
196+
| **browser** | Web automation | `goToPage`, `getHTML`, `screenshot`, `click` |
197+
| **git** | Git operations | `status`, `commit`, `push`, `pull`, `branch` |
198+
| **llm** | Language model interactions | `inference` |
199+
| **chat** | User communication | `sendMessage`, `getChatHistory`, `askQuestion` |
200+
| **tools** | MCP tool integration | `listToolsFromToolBoxes`, `executeTool` |
201+
| **codeutils** | Code analysis | `parseCode`, `extractFunctions`, `getImports` |
202+
| **search** | Content search | `searchInFiles`, `findReferences` |
203+
| **crawler** | Web crawling | `crawlWebsite`, `extractLinks` |
204+
| **vectordb** | Vector operations | `store`, `search`, `similarity` |
205+
| **project** | Project management | `getProjectInfo`, `analyzeStructure` |
206+
| **dbmemory** | Persistent storage | `store`, `retrieve`, `update` |
207+
| **state** | State management | `setState`, `getState`, `clearState` |
208+
| **debug** | Debugging utilities | `log`, `trace`, `profile` |
209+
| **tokenizer** | Text tokenization | `tokenize`, `countTokens` |
210+
211+
## Message Flow
212+
213+
The SDK uses a WebSocket-based communication pattern:
214+
215+
```typescript
216+
// 1. Agent sends request to platform
217+
const response = await codebolt.fs.readFile('./package.json');
218+
219+
// 2. Platform processes request and returns response
220+
// 3. SDK handles response and returns to agent
221+
222+
// For streaming operations:
223+
const stream = codebolt.terminal.executeCommandWithStream('npm install');
224+
stream.on('commandOutput', (data) => {
225+
console.log(data.message);
226+
});
227+
```
228+
229+
## Error Handling
230+
231+
The SDK provides comprehensive error handling:
232+
233+
```typescript
234+
try {
235+
const fileContent = await codebolt.fs.readFile('./nonexistent.txt');
236+
} catch (error) {
237+
if (error.type === 'FileNotFound') {
238+
// Handle file not found
239+
await codebolt.fs.createFile('nonexistent.txt', 'default content', './');
240+
}
241+
}
242+
```
243+
244+
## Best Practices
245+
246+
### 1. **Connection Management**
247+
```typescript
248+
// Always wait for connection before using SDK
249+
await codebolt.waitForConnection();
250+
```
251+
252+
### 2. **Error Handling**
253+
```typescript
254+
// Wrap SDK calls in try-catch blocks
255+
try {
256+
const result = await codebolt.terminal.executeCommand('risky-command');
257+
} catch (error) {
258+
await codebolt.chat.sendMessage(`Error: ${error.message}`);
259+
}
260+
```
261+
262+
### 3. **Resource Cleanup**
263+
```typescript
264+
// Clean up streaming operations
265+
const stream = codebolt.terminal.executeCommandWithStream('long-running-task');
266+
// ... use stream
267+
if (stream.cleanup) {
268+
stream.cleanup();
269+
}
270+
```
271+
272+
### 4. **User Communication**
273+
```typescript
274+
// Keep users informed of progress
275+
await codebolt.chat.sendMessage('Starting file analysis...');
276+
const files = await codebolt.fs.listFile('./', true);
277+
await codebolt.chat.sendMessage(`Found ${files.length} files to analyze`);
278+
```
279+
280+
## Next Steps
281+
282+
- **[Installation & Setup](./installation.md)** - Detailed installation and configuration
283+
- **[Core Modules](./core-modules.md)** - Deep dive into essential modules
284+
- **[Agent Framework](./agent-framework.md)** - Building sophisticated agents
285+
- **[API Reference](./api-reference.md)** - Complete function documentation
286+
- **[Examples](./examples.md)** - Practical implementation examples
287+
- **[Best Practices](./best-practices.md)** - Advanced patterns and techniques
288+
289+
## Support
290+
291+
- **Documentation**: [https://codeboltai.github.io](https://codeboltai.github.io)
292+
- **GitHub**: [https://github.com/codeboltai/codeboltjs](https://github.com/codeboltai/codeboltjs)
293+
- **Community**: Join our Discord for support and discussions
294+
295+
---
296+
297+
The CodeboltJS SDK empowers developers to create intelligent, capable agents that can perform complex development tasks with ease. Start building your first agent today!

‎docusaurus.config.ts

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,10 @@ const config: Config = {
1313
// For GitHub pages deployment, it is often '/<projectName>/'
1414
baseUrl: '/',
1515

16+
markdown: {
17+
mermaid: true,
18+
},
19+
1620
// GitHub pages deployment config.
1721
// If you aren't using GitHub pages, you don't need these.
1822
organizationName: 'codeboltai', // Usually your GitHub org/user name.
@@ -28,6 +32,7 @@ const config: Config = {
2832
defaultLocale: 'en',
2933
locales: ['en'],
3034
},
35+
themes: ['@docusaurus/theme-mermaid'],
3136

3237
presets: [
3338
[
@@ -54,6 +59,9 @@ const config: Config = {
5459
autoCollapseCategories: true,
5560
},
5661
},
62+
mermaid: {
63+
theme: {light: 'neutral', dark: 'forest'},
64+
},
5765
image: 'img/docusaurus-social-card.jpg',
5866
navbar: {
5967
title: 'CodeBolt',

‎package-lock.json

Lines changed: 1373 additions & 50 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
"dependencies": {
1818
"@docusaurus/core": "^3.8.0",
1919
"@docusaurus/preset-classic": "^3.8.0",
20+
"@docusaurus/theme-mermaid": "^3.8.0",
2021
"@mdx-js/react": "^3.0.0",
2122
"clsx": "^2.0.0",
2223
"js-yaml": "^4.1.0",

‎yarn.lock

Lines changed: 941 additions & 16 deletions
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)
Please sign in to comment.