anthropic4s
GitHub
← anthropic4s

Using anthropic4s from Play

Play code works with Future; the SDK is written against Cats Effect. FutureAnthropic sits between the two, so a Play application never has to touch IO.

Pre-release. Nothing is on Maven Central yet: run sbt publishLocal in a checkout of the repository first. anthropic4sVersion below is the version it printed.

docs/play.md · build.sbt
libraryDependencies ++= Seq(
  "io.github.zakariahere" %% "anthropic4s"           % anthropic4sVersion,
  "io.github.zakariahere" %% "anthropic4s-play-json" % anthropic4sVersion
)

Unlike the Java SDK, this needs no dependencyOverrides: there is no Kotlin runtime and no Jackson module to keep in step with Play's.

One client for the application

docs/play.md · One client
import anthropic4s._
import javax.inject.{Inject, Singleton}
import play.api.inject.ApplicationLifecycle
import scala.concurrent.{ExecutionContext, Future}

@Singleton
class Claude @Inject() (lifecycle: ApplicationLifecycle)(implicit ec: ExecutionContext) {

  // Reads ANTHROPIC_API_KEY. Use FutureAnthropic.start(AnthropicConfig(key)) to take it from Play config.
  private val anthropic = FutureAnthropic.fromEnv()
  lifecycle.addStopHook(() => anthropic.close())

  def ask(question: String): Future[String] =
    anthropic
      .create(MessageRequest(Model.ClaudeOpus5_5, 16000, MessageParam.user(question)))
      .map(_.text)
}

Starting the client opens no connection, so it is safe in a constructor.

Errors

A failed call is a failed Future holding an AnthropicError. In a controller:

docs/play.md · Errors
claude.ask(question).map(Ok(_)).recover {
  case _: AnthropicError.RateLimited => TooManyRequests("Busy, try again shortly")
  case e: AnthropicError.Api         => BadGateway(s"Claude said ${e.status}")
  case _: AnthropicError.Timeout     => GatewayTimeout
}

Structured outputs with your Format

docs/play.md · Structured outputs
import anthropic4s.playjson.PlaySchema
import anthropic4s.schema.{description, Schema}
import play.api.libs.json._

final case class Ticket(@description("One-line summary") title: String, urgent: Boolean, assignee: Option[String])

object Ticket {
  implicit val config: JsonConfiguration = PlaySchema.configuration
  implicit val format: OFormat[Ticket]   = Json.format[Ticket]
  implicit val schema: Schema[Ticket]    = PlaySchema.derived[Ticket]
}

val ticket: Future[Ticket] = anthropic.parse[Ticket](request).map(_.value)

Three things to know:

Streaming to the browser

stream calls you back for every event and completes with the whole reply:

docs/play.md · Streaming
def chat(question: String) = Action {
  val (queue, source) = Source.queue[String](64).preMaterialize()
  anthropic
    .streamText(request(question))(text => queue.offer(text))
    .onComplete(_ => queue.complete())
  Ok.chunked(source)
}

The callback runs on the SDK's threads: hand the text off, do not block in it.

Tools

Write tool handlers with Future:

docs/play.md · Tools
final case class FindOrder(@description("Order number") id: String)

val findOrder = FutureAnthropic.tool("find_order", "Looks an order up by its number") { (in: FindOrder) =>
  orderRepository.find(in.id).map(_.fold("No such order")(_.summary))   // Future[String]
}

val answer: Future[String] = anthropic.runTools(request, List(findOrder)).map(_.text)

Going further

anthropic.client is the full AnthropicClient[IO], and anthropic.run(io) turns any SDK effect into a Future. Batches, Files and Models are reached that way:

docs/play.md · Going further
anthropic.run(anthropic.client.models.listAll.compile.toList)   // Future[List[ModelInfo]]