Next Steps

You’ve completed the getting started guide! Here’s where to go next.

Table of contents

  1. 🎉 Congratulations!
  2. Learning Paths
    1. 🤖 Path 1: Build Agents
    2. 🛠️ Path 2: Tool Integration
    3. 💬 Path 3: Conversational AI
    4. 🔍 Path 4: RAG & Knowledge
    5. 📊 Path 5: Production Systems
  3. Quick Reference: Key Features
    1. Agents
    2. Tool Calling
    3. Multi-Turn Conversations
    4. Context Management
    5. Streaming
    6. Observability
    7. Embeddings
    8. MCP Integration
  4. Example Gallery
    1. Basic Examples
    2. Agent Examples
    3. Tool Examples
    4. Context Management Examples
    5. More Examples
  5. Common Recipes
    1. Recipe 1: Simple Q&A Bot
    2. Recipe 2: Agent with Custom Tools
    3. Recipe 3: Streaming Chat
    4. Recipe 4: Multi-Turn with Pruning
  6. Troubleshooting
    1. Common Issues
  7. Community & Support
    1. Get Help
    2. Stay Updated
    3. Contribute
  8. Recommended Learning Order
    1. Week 1: Fundamentals
    2. Week 2: Agents & Tools
    3. Week 3: Advanced Patterns
    4. Week 4: Production
  9. Quick Links
    1. Documentation
    2. Examples
    3. Reference
  10. What to Build?
  11. Ready to Build?

🎉 Congratulations!

You’ve successfully:

✅ Installed LLM4S ✅ Written your first LLM program ✅ Configured providers and API keys ✅ Understood Result-based error handling

Now let’s explore what you can build with LLM4S!

Learning Paths

Choose your path based on what you want to build:

🤖 Path 1: Build Agents

Best for: Interactive applications, chatbots, assistants

What you’ll learn:

  • Agent framework basics
  • Multi-turn conversations
  • Tool calling and integration
  • Conversation state management

Start here:

  1. Agent Framework Guide
  2. Single-Step Agent Example
  3. Multi-Turn Conversations
  4. Tools in the Agents Guide

Example project ideas:

  • Customer support chatbot
  • Code review assistant
  • Research assistant with web search
  • Interactive game master

🛠️ Path 2: Tool Integration

Best for: LLMs that interact with external systems

What you’ll learn:

  • Defining custom tools
  • Tool parameter schemas
  • Model Context Protocol (MCP)
  • Tool error handling

Start here:

  1. Built-in Tools Guide
  2. Weather Tool Example
  3. MCP Tool Example
  4. Multi-Tool Example

Example project ideas:

  • Database query assistant
  • API integration agent
  • File system navigator
  • Task automation system

💬 Path 3: Conversational AI

Best for: Chat applications, dialogue systems

What you’ll learn:

  • Context window management
  • Conversation persistence
  • History pruning strategies
  • Streaming responses

Start here:

  1. Multi-Turn Conversations
  2. Context Window Pruning
  3. Streaming Events Guide
  4. Long Conversation Example

Example project ideas:

  • Slack bot
  • Discord integration
  • Customer service chat
  • Educational tutor

🔍 Path 4: RAG & Knowledge

Best for: Question answering, document search, knowledge bases

What you’ll learn:

  • Vector embeddings
  • Semantic search
  • Document processing
  • Retrieval-augmented generation

Start here:

  1. Vector Store Guide
  2. RAG for Enterprise
  3. Embedding Example
  4. Vector Search

Example project ideas:

  • Documentation Q&A system
  • PDF analyzer
  • Knowledge base search
  • Code search engine

📊 Path 5: Production Systems

Best for: Deploying LLM apps to production

What you’ll learn:

  • Error handling patterns
  • Observability and tracing
  • Performance optimization
  • Security best practices

Start here:

  1. Production Monitoring
  2. Observability Guide
  3. Error Handling
  4. Security Guide

Example project ideas:

  • Scalable API service
  • Multi-tenant SaaS application
  • Enterprise integration
  • Monitoring dashboard

Quick Reference: Key Features

The snippets in this section assume a client: LLMClient (built as in your first program) and, for agents, a tools: ToolRegistry.

Agents

Build sophisticated multi-turn agents with automatic tool calling.

1
2
3
4

import org.llm4s.agent.Agent

val agent = Agent.builder("assistant", client).withTools(tools).build()   // Result[Agent]
val result = agent.flatMap(_.run("Your query"))

Learn more →

Tool Calling

Give LLMs access to external functions and APIs.

1
2
3
4
5
6
7
8
9
10
11

import org.llm4s.toolapi.{ Schema, ToolBuilder }

def search(query: String): String = s"Results for $query"   // your implementation

val searchSchema = Schema
  .`object`[Map[String, Any]]("Search parameters")
  .withProperty(Schema.property("query", Schema.string("What to search for")))

val tool = ToolBuilder[Map[String, Any], String]("search", "Search the web", searchSchema)
  .withHandler(params => params.getString("query").map(search))
  .buildSafe()   // Result[ToolFunction[Map[String, Any], String]]

Learn more →

Multi-Turn Conversations

Functional conversation management without mutation.

1
2
3
4
5
6
7

import org.llm4s.agent.Agent

val turns = for {
  agent   <- Agent.builder("assistant", client).withTools(tools).build()
  result1 <- agent.run("First question")
  result2 <- agent.continueConversation(result1, "Next question")
} yield result2

Learn more →

Context Management

Automatically manage token windows and prune history.

1
2
3
4
5
6

import org.llm4s.agent.{ ContextWindowConfig, PruningStrategy }

val config = ContextWindowConfig(
  maxMessages = Some(20),
  pruningStrategy = PruningStrategy.OldestFirst
)

Learn more →

Streaming

Get real-time token-by-token responses.

1
2
3
4

import org.llm4s.llmconnect.model.{ Conversation, UserMessage }

val conversation = Conversation(Seq(UserMessage("Tell me a story")))
client.streamComplete(conversation, onChunk = chunk => chunk.content.foreach(print))

Learn more →

Observability

Trace LLM calls with Langfuse integration.

1
2

# Automatic tracing when configured (with llm4s-observability on the classpath)
export TRACING_MODE=langfuse

Learn more →

Embeddings

Create and search vector embeddings.

EmbeddingClient (in llm4s-core) turns text into vectors through an embedding provider module, and llm4s-rag indexes and searches them in a vector store.

Learn more →

MCP Integration

Connect to external Model Context Protocol servers.

1
2
3
4

import org.llm4s.mcp.{ MCPServerConfig, MCPToolRegistry }

// llm4s-mcp: an MCPToolRegistry is a ToolRegistry, so an agent takes it like any other
val tools = new MCPToolRegistry(Seq(MCPServerConfig.stdio("files", Seq("npx", "my-mcp-server"))))

Learn more →

Browse the working examples organized by category:

Basic Examples

View all basic examples →

Agent Examples

View all agent examples →

Tool Examples

View all tool examples →

Context Management Examples

View all context examples →

More Examples

Browse all examples →

Common Recipes

Recipe 1: Simple Q&A Bot 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

import org.llm4s.config.Llm4sConfig
import org.llm4s.llmconnect.LLMConnect
import org.llm4s.llmconnect.model._
import org.llm4s.model.ModelRegistryService

def askQuestion(question: String): String = {
  val result = for {
    providerConfig <- Llm4sConfig.defaultProvider()
    registry <- Llm4sConfig.modelRegistryService()
    given ModelRegistryService = registry
    client <- LLMConnect.getClient(providerConfig)
    response <- client.complete(
      Conversation(
        Seq(
          SystemMessage("You are a helpful Q&A assistant."),
          UserMessage(question)
        )
      )
    )
  } yield response.content

  result.fold(_ => "Sorry, I couldn't process that question.", identity)
}

Recipe 2: Agent with Custom Tools 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

import org.llm4s.agent.Agent
import org.llm4s.config.Llm4sConfig
import org.llm4s.llmconnect.LLMConnect
import org.llm4s.model.ModelRegistryService
import org.llm4s.toolapi.{ Schema, ToolBuilder, ToolRegistry }

def getCurrentTime(): String =
  java.time.LocalDateTime.now().toString

val result = for {
  timeTool <- ToolBuilder[Map[String, Any], String](
                "get_time",
                "Get current date and time",
                Schema.`object`[Map[String, Any]]("No parameters")
              ).withHandler(_ => Right(getCurrentTime())).buildSafe()
  providerConfig <- Llm4sConfig.defaultProvider()
  registry <- Llm4sConfig.modelRegistryService()
  given ModelRegistryService = registry
  client <- LLMConnect.getClient(providerConfig)
  agent <- Agent.builder("time-agent", client).withTools(new ToolRegistry(Seq(timeTool))).build()
  result <- agent.run("What time is it?")
} yield result.answer

Recipe 3: Streaming Chat 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import org.llm4s.config.Llm4sConfig
import org.llm4s.llmconnect.LLMConnect
import org.llm4s.llmconnect.model.{ Conversation, UserMessage }
import org.llm4s.model.ModelRegistryService

def streamChat(message: String): Unit = {
  val result = for {
    providerConfig <- Llm4sConfig.defaultProvider()
    registry <- Llm4sConfig.modelRegistryService()
    given ModelRegistryService = registry
    client <- LLMConnect.getClient(providerConfig)
    _ <- client.streamComplete(
      Conversation(Seq(UserMessage(message))),
      onChunk = chunk => chunk.content.foreach(print)
    )
  } yield println()

  result.left.foreach(error => println(s"Error: $error"))
}

Recipe 4: Multi-Turn with Pruning 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

import org.llm4s.agent.{ Agent, ContextWindowConfig, PruningStrategy }
import org.llm4s.agent.graph.middleware.ContextWindowMiddleware

val config = ContextWindowConfig(
  maxMessages = Some(20),
  preserveSystemMessage = true,
  pruningStrategy = PruningStrategy.OldestFirst
)

// Pruning is middleware on the agent: it trims what each model call is sent,
// and the thread keeps the full history (client and tools as in the quick reference above)
val result = for {
  agent  <- Agent.builder("assistant", client)
    .withTools(tools)
    .withMiddleware(ContextWindowMiddleware(config))
    .build()
  first  <- agent.run("First question")                              // Turn 1
  second <- agent.continueConversation(first, "Follow-up question")  // Turn 2, pruned when sent
} yield second

Troubleshooting

Common Issues

Problem: API key errors

  • Check the vendor’s variable is set in the shell that runs your app: echo $OPENAI_API_KEY - a section without an apiKey of its own uses it (API keys)
  • If the section sets its own apiKey = ${?SOME_VAR}, that wins: check SOME_VAR instead
  • Check key starts with correct prefix (sk- for OpenAI, sk-ant- for Anthropic)

Problem: Model not found

  • Verify model in the provider section is the provider’s own model name (e.g. gpt-4o-mini, no openai/ prefix)
  • Check llm4s.providers.provider names the section you meant
  • Check provider supports that model
  • Try a different model

Problem: Slow responses

  • Use streaming for real-time feedback
  • Consider using a faster model (gpt-3.5-turbo, claude-haiku)
  • Check your internet connection

Problem: Token limit errors

  • Implement context window pruning
  • Use shorter system prompts
  • Summarize conversation history

Full troubleshooting guide →

Community & Support

Get Help

Stay Updated

Contribute

  • Starter Kit: Use llm4s.g8 to scaffold projects
  • Share Examples: Post your projects in Discord
  • Contribute: See the contributing guide

Week 1: Fundamentals

  1. ✅ Complete Getting Started (you are here!)
  2. Read Basic Usage Guide
  3. Try Basic Examples
  4. Experiment with different providers

Week 2: Agents & Tools

  1. Read Agent Framework
  2. Build a simple agent with one tool
  3. Try Tool Examples
  4. Add multiple tools

Week 3: Advanced Patterns

  1. Implement Multi-Turn Conversations
  2. Add Context Window Pruning
  3. Set up Observability
  4. Try Long Conversation Example

Week 4: Production

  1. Read Production Monitoring
  2. Implement error handling
  3. Add monitoring and tracing
  4. Deploy your first production agent

Documentation

Examples

Reference

What to Build?

Need inspiration? Here are some project ideas:

Beginner Projects:

  • Simple Q&A bot
  • Code explainer
  • Translation service
  • Writing assistant

Intermediate Projects:

  • Multi-tool research agent
  • Database query interface
  • API integration bot
  • Document summarizer

Advanced Projects:

  • Multi-agent system
  • RAG-powered knowledge base
  • Production chatbot service
  • Custom tool ecosystem

Ready to Build?

Pick your learning path and start building:

🤖 Build Agents

Agent Framework →

🛠️ Add Tools

Tools →

💬 Chat Apps

Multi-Turn →

🔍 RAG Systems

Vector Store →

Happy building with LLM4S! 🚀

Questions? Join our Discord