Skip to main content

Overview

The Faheem Code SDK provides a unified, type-safe framework for building and deploying AI agents—from local experiments to full production systems, focused on statelessness, composability, and clear boundaries between research and deployment.

Check this document for the core design principles that guided its architecture.

Relationship with Faheem Code applications​

The Software Agent SDK is the source of truth for agents in Faheem Code. Its repository also contains Agent Server, which exposes SDK conversations and workspaces to remote clients through REST and WebSocket APIs. Faheem Code applications live in separate repositories and consume these SDK interfaces.

  • The SDK defines agent behavior. It provides agents, LLMs, conversations, tools, workspaces, events, and security policies.
  • Agent Server exposes remote execution. Clients use its APIs to run conversations and tools in the selected workspace or sandbox.
  • Applications remain separate. Faheem Code, the Faheem Code CLI, and custom clients integrate with the SDK or Agent Server without sharing one application repository.

Four-package architecture​

The agent-sdk is organized into four distinct Python packages:

PackageWhat It DoesWhen You Need It
faheemcode.sdkCore agent framework + base workspace classesAlways (required)
faheemcode.toolsPre-built tools (bash, file editing, etc.)Optional - provides common tools
faheemcode.workspaceExtended workspace implementations (Docker, remote)Optional - extends SDK's base classes
faheemcode.agent_serverMulti-user API serverOptional - used by workspace implementations

Two deployment modes​

The SDK supports two deployment architectures depending on your needs:

Mode 1: local development​

Installation: Just install faheemcode-sdk + faheemcode-tools

pip install faheemcode-sdk faheemcode-tools

Architecture:

  • LocalWorkspace included in SDK (no extra install)
  • Everything runs in one process
  • Perfect for prototyping and simple use cases
  • Quick setup, no Docker required

Mode 2: production / sandboxed​

Installation: Install all 4 packages

pip install faheemcode-sdk faheemcode-tools faheemcode-workspace faheemcode-agent-server

Architecture:

  • RemoteWorkspace auto-spawns agent-server in containers
  • Sandboxed execution for security
  • Multi-user deployments
  • Distributed systems (e.g., Kubernetes) support

SDK package (faheemcode.sdk)​

Purpose: Core components and base classes for Faheem Code agent.

Key Components:

  • Agent: Implements the reasoning-action loop
  • Conversation: Manages conversation state and lifecycle
  • LLM: Provider-agnostic language model interface with retry and telemetry
  • Tool System: Typed base class definitions for action, observation, tool, and executor; includes MCP integration
  • Events: Typed event framework (e.g., action, observation, user messages, state update, etc.)
  • Workspace: Base classes (Workspace, LocalWorkspace, RemoteWorkspace)
  • Skill: Reusable user-defined prompts with trigger-based activation
  • Condenser: Conversation history compression for token management
  • Security: Action risk assessment and validation before execution

Design: Stateless, immutable components with type-safe Pydantic models.

Self-Contained: Build and run agents with just faheemcode-sdk using LocalWorkspace.

Source: faheemcode-sdk/

Tools package (faheemcode.tools)​

Purpose: Pre-built tools following consistent patterns.

Design: All tools follow Action/Observation/Executor pattern with built-in validation, error handling, and security.

Workspace package (faheemcode.workspace)​

Purpose: Workspace implementations extending SDK base classes.

Key Components: Docker Workspace, Remote API Workspace, and more.

Design: All workspace implementations extend RemoteWorkspace from SDK, adding container lifecycle or API client functionality.

Use Cases: Sandboxed execution, multi-user deployments, production environments.

Agent server package (faheemcode.agent_server)​

Purpose: FastAPI-based HTTP/WebSocket server for remote agent execution.

Features:

  • REST API & WebSocket endpoints for conversations, bash, files, events, desktop, and VSCode
  • OpenAI-compatible /v1/chat/completions endpoint for clients that expect an OpenAI-style backend
  • Service management with isolated per-user sessions
  • API key authentication and health checking

Deployment: Runs inside containers (via DockerWorkspace) or as standalone process (connected via RemoteWorkspace).

Use Cases: Multi-user web apps, SaaS products, distributed systems.

How components work Together​

Basic execution flow (local)​

When you send a message to an agent, here's what happens:

Key takeaway: The agent orchestrates the reasoning-action loop—calling the LLM for decisions and executing tools to perform actions.

Deployment flexibility​

The same agent code runs in different environments by swapping workspace configuration:

Next steps​

Get started​

Explore components​

SDK Package:

  • Agent – Core reasoning-action loop
  • Conversation – State management and lifecycle
  • LLM – Language model integration
  • Tool System – Action/Observation/Executor pattern
  • Events – Typed event framework
  • Workspace – Base workspace architecture

Tools Package:

Workspace Package:

Agent Server:

Deploy​

Source code​