Skip to content

Guides Overview

These guides provide deep dives into specific features and patterns for building IVCAP lambda services.

Getting Started

If you're new to the SDK, start here:

  1. Installation — Set up the SDK
  2. Quick Start — 5-minute introduction
  3. Your First Lambda Service — Build a real service

Core Concepts

Tool Functions

Learn how to define and register tools: - Request/Result schemas with Pydantic - The @ivcap_lambda decorator and ToolOptions - Accessing JobContext and the FastAPI Request - Async tool functions - Try-later semantics for long-running calls

Read this if: You want to understand the fundamentals of building lambda tool handlers.

Working with Artifacts

Upload and download IVCAP artifacts: - Downloading input artifacts - Uploading results - Handling file streams - Working with collections

Read this if: Your tool processes or generates files.

MCP & Agent Integration

Expose tools to AI agent frameworks, covering both directions: - Adding MCP (--with-mcp/--with-mcp-stdio) to an existing IVCAP lambda service - Building an MCP server first, with IVCAP deployment as an optional bonus - Connecting MCP clients (Claude Desktop, Cline, MCP Inspector) - Tool description endpoints

Read this if: You want your tools to be directly callable by AI agents/MCP hosts via the Model Context Protocol — whether that's your primary goal or an add-on to a REST service.

Advanced Topics

Observability & Logging

Monitor your services: - Structured logging with getLogger and logging_init - Progress events and step reporting - OpenObserve integration - OpenTelemetry tracing with FastAPI

Read this if: You want comprehensive monitoring and debugging.

Error Handling

Build robust services: - Exception handling patterns - Reporting errors through the event system - HTTP status codes returned - Graceful degradation

Read this if: You need production-grade error handling.

Deployment

Deploy to production: - Docker containerization - Environment configuration - Service registration with IVCAP - Kubernetes patterns

Read this if: You're ready to deploy your service.

Best Practices

Pro tips and patterns: - Code organization - Testing strategies - Performance optimization - Common pitfalls

Read this if: You want to write production-quality code.

Learning Path

Installation
    ↓
Quick Start
    ↓
Your First Lambda Service
    ↓
Tool Functions
    ├→ Artifacts (if needed)
    ├→ MCP & Agent Integration (if needed)
    └→ Observability (if needed)
    ↓
Error Handling
    ↓
Deployment
    ↓
Best Practices

Choose Your Own Path

See Also