LLM
The LLM type initializes a Large Language Model (LLM).
ENV TYPEYou use an LLM in conjunction with Env. The Env type is used to represent the environment in which an LLM operates. It allows the LLM to interact with inputs and outputs, such as directories, containers, and custom modules.
API reference
A conversation with a large language model (LLM): queue prompts, expose tools, and step the model until it completes its turn.
contextTokens- estimated number of tokens currently occupying the context window; unlike tokenUsage this is not cumulative over the session
contextWindow- The model's total context window in tokens, or null if unknown (e.g. a local or uncatalogued model).
hasPending- Report whether anything is queued to send to the model: an unsent prompt or unevaluated tool results. When true, another step will do work; when false, the turn is complete.
id- A unique identifier for this LLM.
lastReply- The text of the model's most recent reply.
model- The model the conversation is running against, after resolving any configured default.
portableID- A portable, self-contained ID for the conversation that node() can resolve in any session. Unlike id, which may return an engine-local runtime handle valid only within the current session, this returns the recipe form suitable for persisting and later restoring the conversation. The recipe is flattened: bindings superseded during the session (workspace overlays recorded by each mutating tool call, and re-bound toolsets) are dropped, while the current workspace binding — including any pending, un-exported edits — is preserved.
provider- The provider serving the model, e.g. "anthropic", "openai", "google", or "local".
reasoningEffort- The reasoning effort in use, e.g. "low", "medium", or "high". Empty or "none" when reasoning is disabled.
tools- Render documentation for the tools currently exposed to the model.
transcript- The message history rendered as a plain-text transcript, suitable for feeding back to an LLM (e.g. for summarization).
agent- Reconstruct a spawned agent from its runtime handle.
emitHistory- Re-emit telemetry spans for the full message history, so a loaded conversation displays in the TUI.
fork- Fork the conversation, so that otherwise-identical follow-ups evaluate independently instead of deduplicating to a single cached result.
loop- Send the queued prompt and step the model against the available tools, until it ends its turn: a reply with no tool calls and nothing left queued.
messages- The full message history, as structured messages.
skills- The skills visible to the model, exactly as the ListSkills tool serves them: engine-embedded skills, skills installed with withSkills, and skills discovered in the workspace.
spawn- Spawn the conversation as an agent: a startable, addressable evaluation loop seeded with this conversation's state, tools, and workspace.
step- Advance the conversation by a single step: send the queued prompt or tool results to the model, evaluate any tool calls it makes, and queue their results. Use loop to step until the model ends its turn.
sync- Force evaluation of the conversation's pending operations (prompts, steps, loops) in the engine.
tokenUsage- The cumulative token usage, summed across every API call in the conversation.
withMCPServer- Add an external MCP server to the LLM
withModel- Change the model for the rest of the conversation. The message history is preserved; the new model takes effect on the next step.
withoutDefaultSystemPrompt- Disable the default system prompt
withoutMessageHistory- Clear the message history, keeping only the system prompts.
withoutSystemPrompts- Clear the user-added system prompts, keeping only the default system prompt.
withPrompt- Queue a user prompt, to be sent to the model on the next step or loop.
withPromptFile- Queue a file's contents as a user prompt, like withPrompt.
withReasoningEffort- Change the reasoning effort for the rest of the conversation, overriding any configured default. The message history is preserved; the new effort takes effect on the next step.
withResponse- Append an assistant response to the message history without calling the model, e.g. to reconstruct a conversation from another source.
withSkills- Install skills from a directory, adding them to the skills the model discovers with ListSkills and reads with ReadSkill. Each skill is a directory containing a SKILL.md with name and description frontmatter, discovered anywhere in the tree. Installed skills take precedence over skills discovered in the workspace, but cannot shadow the engine's built-in skills.
withSmallModel- Switch to the configured small model for the current provider, or that provider's recommended default. The message history is preserved; unknown providers without a small-model configuration keep their current model.
withSystemPrompt- Add a system prompt, instructing the model across the whole conversation.
withToolResult- Append the result of a tool call to the message history.
withTools- Expose an object's methods as tools. Every eligible method of the bound object becomes a tool; a tool that returns this object's own type replaces it as the new state. Repeatable to bind several objects.
withWorkspace- Bind the LLM to a workspace, exposing its modules as tools exactly as the Dagger CLI would serve them for that workspace.
workspace- Return the workspace the LLM is bound to.
contextTokens: Int!
estimated number of tokens currently occupying the context window; unlike tokenUsage this is not cumulative over the session
contextWindow: Int
The model's total context window in tokens, or null if unknown (e.g. a local or uncatalogued model).
hasPending: Boolean!
Report whether anything is queued to send to the model: an unsent prompt or unevaluated tool results. When true, another step will do work; when false, the turn is complete.
id: ID!
A unique identifier for this LLM.
lastReply: String!
The text of the model's most recent reply.
model: String!
The model the conversation is running against, after resolving any configured default.
portableID: ID!
A portable, self-contained ID for the conversation that node() can resolve in any session. Unlike id, which may return an engine-local runtime handle valid only within the current session, this returns the recipe form suitable for persisting and later restoring the conversation. The recipe is flattened: bindings superseded during the session (workspace overlays recorded by each mutating tool call, and re-bound toolsets) are dropped, while the current workspace binding — including any pending, un-exported edits — is preserved.
provider: String!
The provider serving the model, e.g. "anthropic", "openai", "google", or "local".
reasoningEffort: String!
The reasoning effort in use, e.g. "low", "medium", or "high". Empty or "none" when reasoning is disabled.
tools: String!
Render documentation for the tools currently exposed to the model.
transcript: String!
The message history rendered as a plain-text transcript, suitable for feeding back to an LLM (e.g. for summarization).
agent(handle: String!, name: String!): Agent!Experimental
Reconstruct a spawned agent from its runtime handle.
This is the lookup spawn pins its result's identity through: the returned handle's ID is an honest, replayable chain denoting the one instance the spawn minted. It never creates an instance itself.
Experimental: Agent APIs are likely to change.
handle: String!The opaque runtime handle minted by the spawn that created the agent.
name: String!The agent's display name, as recorded by the spawn.
emitHistory: LLM!
Re-emit telemetry spans for the full message history, so a loaded conversation displays in the TUI.
fork(label: String!): LLM!
Fork the conversation, so that otherwise-identical follow-ups evaluate independently instead of deduplicating to a single cached result.
label: String!A label distinguishing this fork from its siblings, e.g. "attempt-2" when retrying a flaky evaluation.
loop(maxSteps: Int, maxTokens: Int): LLM!
Send the queued prompt and step the model against the available tools, until it ends its turn: a reply with no tool calls and nothing left queued.
maxSteps: IntCap the number of steps. The loop fails if the cap is reached before the model ends its turn.
maxTokens: IntCap the model's output tokens on each step. Defaults to the model's maximum.
messages: [LLMMessage!]!
The full message history, as structured messages.
skills: [LLMSkill!]!
The skills visible to the model, exactly as the ListSkills tool serves them: engine-embedded skills, skills installed with withSkills, and skills discovered in the workspace.
spawn(name: String,handle: String,state: AgentState = IDLE,error: String = ""): Agent!Experimental
Spawn the conversation as an agent: a startable, addressable evaluation loop seeded with this conversation's state, tools, and workspace.
Every spawn mints a unique agent instance — two spawns of an identical conversation are two distinct agents, like two calls to a process spawn. The result is pinned to the instance (via the agent lookup field), so re-loading its ID re-addresses the same agent from any request in the session.
The loop is not started: the agent spends nothing until it is prompted or resumed, and any input pending on the conversation is stepped then.
With a handle, spawn restores an instance instead of minting one: this conversation becomes the committed history of the agent that handle names, so prompting it continues where it left off — rebuild a conversation's ID from a trace, load it, and spawn it under the handle it belonged to. Fails if that instance already has a runtime entry in this session: a restore must happen before anything else addresses the instance, since by then it may have stepped.
Experimental: Agent APIs are likely to change.
name: StringDisplay label for the agent — telemetry and error messages; carries no identity. Defaults to a short name derived from the conversation.
handle: StringThe runtime handle to restore the instance under, as published on its loop span as dagger.io/agent.id. Omit to mint a fresh instance.
state: AgentState = IDLEThe lifecycle state to create the agent in, as facts on the entry: IDLE is ready to be prompted, PAUSED parks it, FAILED holds an error a resume retries past, STOPPED preserves a dormant snapshot that send or resume can relaunch.
RUNNING and WAITING_INPUT are refused: they describe a loop, and a restored loop died with the session that published it — restore such an agent as IDLE, its interrupted turn's input still pending on the conversation.
error: String = ""The loop error to create the agent with, for state FAILED. Refused with any other state.
step(maxTokens: Int): LLM!
Advance the conversation by a single step: send the queued prompt or tool results to the model, evaluate any tool calls it makes, and queue their results. Use loop to step until the model ends its turn.
maxTokens: IntCap the model's output tokens for this step. Defaults to the model's maximum.
sync: LLM!
Force evaluation of the conversation's pending operations (prompts, steps, loops) in the engine.
tokenUsage: LLMTokenUsage!
The cumulative token usage, summed across every API call in the conversation.
withMCPServer(name: String!, service: Service!): LLM!
Add an external MCP server to the LLM
name: String!The name of the MCP server
service: Service!The MCP service to run and communicate with over stdio
withModel(model: String!, provider: String): LLM!
Change the model for the rest of the conversation. The message history is preserved; the new model takes effect on the next step.
model: String!The model to use, e.g. "claude-sonnet-4-5" or "gpt-5.4".
provider: StringThe provider serving the model, e.g. "openai". Overrides the provider otherwise inferred from the model name — useful when the name matches no known pattern (e.g. a fine-tune), or matches the wrong one.
withoutDefaultSystemPrompt: LLM!
Disable the default system prompt
withoutMessageHistory: LLM!
Clear the message history, keeping only the system prompts.
withoutSystemPrompts: LLM!
Clear the user-added system prompts, keeping only the default system prompt.
withPrompt(prompt: String!, origin: LLMMessageOriginInput): LLM!
Queue a user prompt, to be sent to the model on the next step or loop.
prompt: String!The prompt to send
origin: LLMMessageOriginInputThe message's recorded provenance, when it arrived through an agent mailbox rather than from the user. Rendered to the model as an attribution header at request-build time.
withPromptFile(file: File!): LLM!
Queue a file's contents as a user prompt, like withPrompt.
file: File!The file to read the prompt from
withReasoningEffort(effort: String!): LLM!
Change the reasoning effort for the rest of the conversation, overriding any configured default. The message history is preserved; the new effort takes effect on the next step.
effort: String!The reasoning effort, e.g. "low", "medium", or "high"; "none" disables reasoning. Supported levels are model-specific — some models also accept e.g. "minimal", "xhigh", or "max".
withResponse(content: [LLMContentBlockInput!]!,inputTokens: Int = 0,outputTokens: Int = 0,cachedTokenReads: Int = 0,cachedTokenWrites: Int = 0,totalTokens: Int = 0): LLM!
Append an assistant response to the message history without calling the model, e.g. to reconstruct a conversation from another source.
content: [LLMContentBlockInput!]!The response content
inputTokens: Int = 0Uncached input tokens sent
outputTokens: Int = 0Tokens received from the model, including text and tool calls
cachedTokenReads: Int = 0Cached input tokens read
cachedTokenWrites: Int = 0Cached input tokens written
totalTokens: Int = 0Total tokens consumed by this response
withSkills(directory: Directory!): LLM!
Install skills from a directory, adding them to the skills the model discovers with ListSkills and reads with ReadSkill. Each skill is a directory containing a SKILL.md with name and description frontmatter, discovered anywhere in the tree. Installed skills take precedence over skills discovered in the workspace, but cannot shadow the engine's built-in skills.
directory: Directory!A directory containing skills, each a subdirectory holding a SKILL.md.
withSmallModel: LLM!
Switch to the configured small model for the current provider, or that provider's recommended default. The message history is preserved; unknown providers without a small-model configuration keep their current model.
withSystemPrompt(prompt: String!): LLM!
Add a system prompt, instructing the model across the whole conversation.
prompt: String!The system prompt to send
withToolResult(callId: String!,content: String!,errored: Boolean!): LLM!
Append the result of a tool call to the message history.
callId: String!The ID of the tool call this result responds to
content: String!The content returned by the tool
errored: Boolean!Whether the tool call resulted in an error
withTools(object: Node!, except: [String!] = []): LLM!
Expose an object's methods as tools. Every eligible method of the bound object becomes a tool; a tool that returns this object's own type replaces it as the new state. Repeatable to bind several objects.
object: Node!The object whose methods become tools.
except: [String!] = []Method names to exclude from the toolset (e.g. constructors, entrypoints).
withWorkspace(workspace: Workspace!): LLM!
Bind the LLM to a workspace, exposing its modules as tools exactly as the Dagger CLI would serve them for that workspace.
workspace: Workspace!The workspace to work in.