open() function is the main entry point for Thinkwell. It connects to an AI agent (like Claude Code) and returns an Agent instance with a fluent API for blending deterministic code with LLM-powered reasoning.
Opening an Agent
Useopen() to establish a connection to an AI agent by name.
Named Agents
Thinkwell provides built-in support for popular AI agents:Custom Commands
You can also connect using any custom command that implements the Agent Client Protocol:Connection Options
Theopen() function accepts optional configuration:
Environment Variable Overrides
open() checks two environment variables before resolving the agent:
$THINKWELL_AGENT— an agent name:THINKWELL_AGENT=opencode thinkwell script.ts$THINKWELL_AGENT_CMD— a command string:THINKWELL_AGENT_CMD="myagent --acp" thinkwell script.ts
$THINKWELL_AGENT_CMD takes precedence. Either way, the env override applies regardless of what the script passes to open(). This lets you swap agents at runtime without changing code.
Ephemeral vs Persistent Sessions
Thinkwell supports two patterns for interacting with agents:Ephemeral Sessions (Single-Turn)
Useagent.think() for one-off prompts that don’t need conversation history. Each call creates an ephemeral session that is automatically closed when the prompt completes.
- Independent, self-contained tasks
- Stateless operations that don’t need context
- Parallel processing of multiple prompts
Persistent Sessions (Multi-Turn)
Useagent.createSession() for multi-turn conversations where the agent needs to remember previous interactions.
- Multi-step workflows where context matters
- Iterative refinement of results
- Conversations that build on previous responses
Code Examples
Basic Prompt with Structured Output
Using Custom Tools
Multi-Turn Session with Working Directory
API Reference
open(name, options?)
Opens a connection to a named agent.
Parameters:
Returns:
Promise<Agent>
open(options)
Opens a connection using a custom command.
Parameters:
Returns:
Promise<Agent>
AgentOptions:
CustomAgentOptions (extends AgentOptions):
agent.think(schema)
Creates a Plan for constructing a single-turn prompt. Each call creates an ephemeral session that is automatically closed when the prompt completes.
Parameters:
Returns:
Plan<Output>
agent.createSession(options?)
Creates a persistent session for multi-turn conversations.
Parameters:
Returns:
Promise<Session>
SessionOptions:
agent.close()
Closes the connection to the agent. This shuts down the conductor and invalidates any active sessions.
Returns: void
See Also
- API Overview - Plan methods and schema providers
- Sessions - Multi-turn conversation sessions
