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.
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
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:
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
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:
-
PlaySchema.configurationmakesJson.formatwrite a missingOptionasnulland tag sealed traits with atypefield. That is the shape the schema promises the model will send. -
A sealed trait of case objects is described to the model as a list of strings. Give it a
Formatthat reads strings:PlaySchema.enumFormat("Low" -> Low, "High" -> High). -
Json.formatcannot see the cases of a sealed trait when they are declared inside the same companion object that calls it. Declare the cases at the top level.
Streaming to the browser
stream calls you back for every event and completes with the whole reply:
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:
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:
anthropic.run(anthropic.client.models.listAll.compile.toList) // Future[List[ModelInfo]]