> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/anthropics/claude-agent-sdk-python/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with the Claude Agent SDK and build your first agent in minutes

## Your first query

The simplest way to interact with Claude is using the `query()` function. Here's a complete working example:

```python theme={null}
import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="What is 2 + 2?"):
        print(message)

anyio.run(main)
```

<Note>
  The `query()` function is an async function that returns an `AsyncIterator` of response messages.
</Note>

## Understanding the response

To extract specific content from Claude's responses, check the message type and content blocks:

```python theme={null}
from claude_agent_sdk import query, AssistantMessage, TextBlock

async for message in query(prompt="What is 2 + 2?"):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if isinstance(block, TextBlock):
                print(f"Claude: {block.text}")
```

## Configuring with options

Customize Claude's behavior using `ClaudeAgentOptions`:

```python theme={null}
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

options = ClaudeAgentOptions(
    system_prompt="You are a helpful assistant that explains things simply.",
    max_turns=1,
)

async for message in query(
    prompt="Explain what Python is in one sentence.",
    options=options
):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if isinstance(block, TextBlock):
                print(f"Claude: {block.text}")
```

## Using tools

Enable Claude to perform actions like reading and writing files:

```python theme={null}
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write"],
    system_prompt="You are a helpful file assistant.",
)

async for message in query(
    prompt="Create a file called hello.txt with 'Hello, World!' in it",
    options=options,
):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if isinstance(block, TextBlock):
                print(f"Claude: {block.text}")
```

<Warning>
  By default, Claude will ask for permission before using tools. To auto-accept file edits, set `permission_mode='acceptEdits'` in your options.
</Warning>

### Auto-accepting tool usage

```python theme={null}
options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Bash"],
    permission_mode='acceptEdits'  # Auto-accept file edits
)
```

## Setting the working directory

Specify a working directory for file operations:

```python theme={null}
from pathlib import Path
from claude_agent_sdk import ClaudeAgentOptions

options = ClaudeAgentOptions(
    cwd="/path/to/project"  # or Path("/path/to/project")
)
```

## Complete example

Here's a complete example combining multiple concepts:

```python theme={null}
import anyio
from claude_agent_sdk import (
    AssistantMessage,
    ClaudeAgentOptions,
    ResultMessage,
    TextBlock,
    query,
)

async def main():
    # Configure options
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write"],
        system_prompt="You are a helpful file assistant.",
        max_turns=5,
    )
    
    # Send query
    async for message in query(
        prompt="Create a file called hello.txt with 'Hello, World!' in it",
        options=options,
    ):
        # Handle assistant responses
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(f"Claude: {block.text}")
        
        # Handle result with cost information
        elif isinstance(message, ResultMessage) and message.total_cost_usd > 0:
            print(f"\nCost: ${message.total_cost_usd:.4f}")

if __name__ == "__main__":
    anyio.run(main)
```

## Next steps

<CardGroup cols={2}>
  <Card title="Client API" icon="comments" href="/api/claude-sdk-client">
    Build interactive, bidirectional conversations
  </Card>

  <Card title="Custom tools" icon="wrench" href="/guides/custom-tools">
    Create your own tools for Claude to use
  </Card>

  <Card title="Hooks" icon="hook" href="/guides/hooks">
    Add custom logic to the agent loop
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/core-concepts/error-handling">
    Handle errors gracefully in your application
  </Card>
</CardGroup>