# query() Function

> The main function of the kit. Give it a prompt, and it runs the agent and sends back each step.

**Field:** Artificial Intelligence  
**Category:** Claude Agent SDK  
**Also known as:** query(), Agent SDK query, Claude Agent SDK query()

## Think of it like

It is like giving a helper a job. They tell you each step.

## Definition

query() is the main function of the Agent SDK. You pass it a prompt and an options object, and it starts the agent loop. It returns a stream you read with a loop, and each item is a message: a tool call, a tool result, some text, or the final result. One call can run many turns before it ends.

## Example

Leo calls query() with the prompt find and fix the bug in utils.py. His loop prints each tool Claude uses, then the result.

## Example code

```typescript
for await (const m of query({ prompt: "Fix the failing test" })) {
  if (m.type === "result") console.log(m.result);
}
```

Run one task and print the final result.

## Why it matters

It is the one way in to the agent, so most programs start here.

## Common mistake

Waiting for one return value. query() streams messages, so read them in a loop.

## Three principles

- **Prompt and options in.** Messages out.
- **Runs the whole loop.** Many turns.
- **Read it in a loop.** async for.

## Related terms

- [ClaudeAgentOptions](https://learn.benibix.com/term/ai/claude-agent-options)
- [ResultMessage](https://learn.benibix.com/term/ai/sdk-result-message)
- [ClaudeSDKClient](https://learn.benibix.com/term/ai/claude-sdk-client)
- [Agent Loop](https://learn.benibix.com/term/ai/agent-loop)

## Told apart from

- [query() vs ClaudeSDKClient](https://learn.benibix.com/compare/query-function-vs-claude-sdk-client): People think query() and ClaudeSDKClient are two names for the same thing. query() runs a task and ends, and each new call starts fresh unless you pass resume or continue. ClaudeSDKClient is a Python class that keeps one session open, so each prompt you send remembers the ones before. Use query() for one job, and the client for a chat.

![The messages one run yields in order: a SystemMessage to start, AssistantMessage and UserMessage pairs for each tool call, and a ResultMessage at the end.](https://learn.benibix.com/diagrams/agent-sdk-message-stream.svg)

---

Source: https://learn.benibix.com/term/ai/query-function
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-20
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
