ClaudeAgentSDK.Query (claude_agent_sdk v0.6.9)

View Source

Handles querying Claude Code and processing responses.

This module is responsible for building the appropriate command-line arguments for different types of Claude Code queries (new queries, continuations, and resumptions) and delegating to the Process module for execution.

All functions in this module return a Stream of ClaudeAgentSDK.Message structs.

SDK MCP Server Support

When SDK MCP servers are detected in options, the query automatically uses the Client GenServer (which supports bidirectional control protocol) instead of the simpler Process.stream approach. This is transparent to the caller - you still get the same Stream interface.

Summary

Functions

continue(prompt, options)

Continues the most recent conversation.

resume(session_id, prompt, options)

Resumes a specific conversation by session ID.

run(prompt, options)

Runs a new query with the given prompt and options.

Functions

continue(prompt, options)

@spec continue(String.t() | nil, ClaudeAgentSDK.Options.t()) ::
  Enumerable.t(ClaudeAgentSDK.Message.t())

Continues the most recent conversation.

Parameters

Returns

A stream of ClaudeAgentSDK.Message.t/0 structs.

Examples

ClaudeAgentSDK.Query.continue("Add error handling", %ClaudeAgentSDK.Options{})

resume(session_id, prompt, options)

@spec resume(String.t(), String.t() | nil, ClaudeAgentSDK.Options.t()) ::
  Enumerable.t(ClaudeAgentSDK.Message.t())

Resumes a specific conversation by session ID.

Parameters

  • session_id - The session ID to resume (string)
  • prompt - Optional additional prompt to send (string or nil)
  • options - Configuration options (see ClaudeAgentSDK.Options.t/0)

Returns

A stream of ClaudeAgentSDK.Message.t/0 structs.

Examples

ClaudeAgentSDK.Query.resume("session-123", "Add tests", %ClaudeAgentSDK.Options{})

run(prompt, options)

@spec run(String.t(), ClaudeAgentSDK.Options.t()) ::
  Enumerable.t(ClaudeAgentSDK.Message.t())

Runs a new query with the given prompt and options.

Automatically detects if SDK MCP servers are present in options and routes to the appropriate backend:

  • SDK MCP servers present → Uses Client GenServer (bidirectional control protocol)
  • No SDK MCP servers → Uses Process.stream (simple unidirectional streaming)

Parameters

Returns

A stream of ClaudeAgentSDK.Message.t/0 structs.

Examples

# Simple query (no SDK MCP)
ClaudeAgentSDK.Query.run("Write a hello world function", %ClaudeAgentSDK.Options{})

# With SDK MCP servers (auto-uses Client)
server = ClaudeAgentSDK.create_sdk_mcp_server(name: "math", tools: [Add])
options = %Options{mcp_servers: %{"math" => server}}
ClaudeAgentSDK.Query.run("What is 2+2?", options)