Skip to main content

Getting Started

This guide will help you get Agent Codemode up and running quickly.

Installation​

Install Agent Codemode using pip:

pip install agent-codemode

For development or to get the latest features:

pip install git+https://github.com/datalayer/agent-codemode.git

Prerequisites​

  • Python 3.10 or later
  • MCP servers you want to connect to (e.g., filesystem, bash, web)

Basic Setup​

1. Create a Tool Registry​

The ToolRegistry manages connections to MCP servers and tracks available tools:

from agent_codemode import ToolRegistry, MCPServerConfig

# Create a registry
registry = ToolRegistry()

# Add an MCP server (stdio transport)
registry.add_server(MCPServerConfig(
    name="filesystem",
    transport="stdio",
    command="npx",
    args=["-y", "@anthropic/mcp-server-filesystem", "/tmp"]
))

# Add another server (HTTP transport)
registry.add_server(MCPServerConfig(
    name="web",
    transport="http",
    url="http://localhost:8001"
))

# Discover tools from all servers
await registry.discover_all()

# List available tools
for tool in registry.list_tools():
    print(f"{tool.name}: {tool.description}")

2. Set Up the Executor​

The CodeModeExecutor runs Python code that uses MCP tools:

from agent_codemode import CodeModeExecutor

# Create executor with the registry
executor = CodeModeExecutor(registry)

# Set up (generates tool bindings)
await executor.setup()

3. Execute Code​

Now you can run code that composes MCP tools:

result = await executor.execute("""
    from generated.servers.filesystem import read_file, write_file
    
    # Read a file
    content = await read_file({"path": "/tmp/input.txt"})
    
    # Process it
    processed = content.upper()
    
    # Write the result
    await write_file({"path": "/tmp/output.txt", "content": processed})
    
    print(f"Processed {len(content)} characters")
""")

print(result.output)  # "Processed 42 characters"
print(result.success) # True

Complete Example​

Here's a complete example putting it all together:

import asyncio
from agent_codemode import ToolRegistry, CodeModeExecutor, MCPServerConfig

async def main():
    # Set up registry
    registry = ToolRegistry()
    registry.add_server(MCPServerConfig(
        name="filesystem",
        transport="stdio",
        command="npx",
        args=["-y", "@anthropic/mcp-server-filesystem", "/workspace"]
    ))
    await registry.discover_all()
    
    # Set up executor
    executor = CodeModeExecutor(registry)
    await executor.setup()
    
    # Execute code
    result = await executor.execute("""
        from generated.servers.filesystem import list_directory, read_file
        import asyncio
        
        # List files
        entries = await list_directory({"path": "/"})
        print(f"Found {len(entries['entries'])} files")
        
        # Read all text files in parallel
        txt_files = [e for e in entries['entries'] if e.endswith('.txt')]
        contents = await asyncio.gather(*[
            read_file({"path": f"/{f}"}) for f in txt_files
        ])
        
        total_chars = sum(len(c) for c in contents)
        print(f"Total characters: {total_chars}")
    """)
    
    if result.success:
        print("Execution successful!")
        print(result.output)
    else:
        print(f"Execution failed: {result.error}")

asyncio.run(main())

Next Steps​

When using Agent Codemode with an AI agent, use this system prompt to guide the agent's behavior:

You are an AI assistant with access to tools via MCP.

## Available Tools
You have access to these meta-tools:
1. **list_tool_names** - Fast listing of tool names (use get_tool_details to get schemas)
2. **search_tools** - AI-powered tool discovery (returns full tool definitions)
3. **get_tool_details** - Get the full schema for a specific tool
4. **execute_code** - Execute Python code in a sandboxed environment

## Tool Execution Model
ALL actual tool execution (file operations, web requests, etc.) must be done by writing Python code that runs in the sandbox.
You CANNOT directly call tools - you must write code that imports and uses the generated tool bindings.

## Workflow
1. **Discover tools** using search_tools, list_tool_names, or get_tool_details
2. **Write Python code** that imports tools from generated bindings
3. **Execute your code** using execute_code

## Code Examples

Simple tool call:
```python
from generated.servers.filesystem import read_file
content = await read_file({"path": "/data/config.json"})
print(content)

Parallel operations:

import asyncio
from generated.servers.filesystem import read_file

files = ["/data/a.txt", "/data/b.txt", "/data/c.txt"]
contents = await asyncio.gather(*[read_file({"path": f}) for f in files])
for f, c in zip(files, contents):
    print(f"{f}: {len(c)} chars")

Error handling:

from generated.servers.filesystem import read_file, write_file

try:
    content = await read_file({"path": "/data/input.txt"})
    await write_file({"path": "/output/result.txt", "content": content.upper()})
except Exception as e:
    print(f"Error: {e}")

Building Skills​

You can save Python files to the skills directory to create reusable scripts. Skills can be imported and composed, enabling complex workflows. Use save_skill to persist useful code patterns for future use.


This system prompt teaches the agent:
1. The meta-tools available for discovery
2. That all execution must go through `execute_code`
3. How to import and use generated tool bindings
4. Common code patterns (parallel, error handling)