Libraries
Add typed capabilities, dynamic prompts and pluggable implementations to actors
Often, we want to extend our actors with external capabilities so they can interact with the world and accomplish goals. In Tardigrade, these are defined using libraries. You can think of them as an Effect native plugin system for agents, giving them typed capabilities with pluggable implementations.
A Tardigrade library is a named group of typed Rpc methods with annotations, an Effect Service that backs them, and dynamic model prompts. This enables strong type level guarantees, automatic dependency injection and seamless integration with the rest of your Effect application. Once defined, application hosts provide service implementations using Effect Layer.
Library = Effect Service + RPC contract + Dynamic prompts
▲ ▲ ▲
│ │ └── System and user context
│ └── Typed methods and annotations
└── Implemented through a Layer
The following example illustrates this through a workspace capability that lets an agent use a filesystem and execute bash commands. This capability is also provided as a first-party library.
Contract
Every capability starts with an interface. Interfaces provide contracts for how a capability can be used. For the workspace library, we start by writing the Rpc contracts for bash, read, write and edit methods. Tardigrade’s Library.make derives an Effect service tag and its method types from annotated Rpc contracts.
import { Schema } from "effect"
import { Rpc } from "effect/rpc"
import { Library, MethodDescription } from "tardie/libraries"
// BashInput and BashOutput define the command schema.
export const BashInput = Schema.Struct({ command: Schema.String })
export const BashOutput = Schema.String
// Other method schemas omitted.
// WorkspaceError is shared by all methods.
export const WorkspaceError = Schema.String
// workspace defines the RPC contract and its Effect service tag.
export const workspace = Library.make(
"workspace",
Rpc.make("bash", {
payload: BashInput,
success: BashOutput,
error: WorkspaceError,
}).annotate(MethodDescription, "Run a shell command in the workspace"),
// read, write, and edit omitted.
)
Context
To steer your agents better, a library lets you append prompt chunks to the system or user prompt dynamically. For static prompts, pass a string to the system or user option of the Library.context method. For dynamic prompts, run an effect that resolves to the prompt string.
For example, for the workspace library, the system prompt could be a static description of the tool whereas the user prompt could dynamically return the latest state of the working directory.
import { Effect } from "effect"
import { Library } from "tardie/libraries"
import { workspace } from "./workspace"
workspace.pipe(
Library.context({
system: "Use workspace tools to inspect and modify files.",
user: Effect.flatMap(workspace, service =>
service.bash({ command: "find . -type f | sort" }),
),
}),
)
To replace only the system instructions while preserving the user context, supply just system.
workspace.pipe(
Library.context({
system: "Inspect files before making changes.",
}),
)
To disable context supplied by another library, pass null.
workspace.pipe(Library.context(null))
Agent
Once your library is defined, it can be added to the agent tools array. Your agent now declares its tools and the services required to run them.
import { Effect } from "effect"
import { Agent } from "tardie/agent"
import { Actor } from "tardie/core"
import { workspace } from "./workspace"
const program = Effect.gen(function* () {
const tools = yield* Agent.tools([workspace])
const context = yield* Agent.compact(Agent.messages)
return yield* Agent.make({
system: "Use the workspace to read and edit files and run shell commands.",
tools,
context,
})
})
export const assistant = Actor.make("assistant", program)
Hosting
If services and libraries describe the contract, layers describe how they can be implemented in reality. This matters when the same capability can be implemented in different ways.
For example, one way to implement the Workspace library is using a real filesystem and bash through a container. The same library can also be implemented using virtual filesystem and bash, backed by SQLite. This can be done by simply swapping the layer when hosting. Tardigrade provides platform layers for local filesystems, Cloudflare containers, and SQLite-backed virtual filesystems.
To create your own platform layer, map the effect service methods to their corresponding implementations.
import { Effect, Layer } from "effect"
import { workspace } from "../workspace"
import { MyFilesystem, filesystemLayer } from "../filesystem"
export const workspaceLayer = Layer.effect(workspace,
Effect.map(MyFilesystem, fs => ({
bash: ({ command }) => fs.execute(command),
// read, write, and edit omitted.
})),
).pipe(Layer.provide(filesystemLayer))
Supply your implementation layers to the platform host through its layer option. Missing service requirements are caught at compile time.
import { Layer } from "effect"
import { host } from "tardie/platform/cloudflare"
import { assistant } from "./agent"
import { modelLayer } from "./layers/model"
import { workspaceLayer } from "./layers/workspace"
const worker = host(assistant, {
layer: Layer.mergeAll(modelLayer, workspaceLayer),
})
Next steps
Now that you know the basic concepts behind libraries, you are ready to create your own capabilities. Tardigrade also comes with a few native libraries that you can easily plug into your agent. Check them here.