> ## Documentation Index
> Fetch the complete documentation index at: https://docs.egregorelabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart Guide

> Get up and running with Egregore in 5 minutes

# Quickstart Guide

Get started with Egregore in just a few minutes and create your first AI agent with PACT architecture.

## Installation

<CodeGroup>
  ```bash pip theme={null}
  pip install egregore
  ```

  ```bash poetry theme={null}
  poetry add egregore
  ```
</CodeGroup>

## Setup API Key

Egregore supports 30+ AI providers. Set up your preferred provider's API key:

<CodeGroup>
  ```bash OpenAI theme={null}
  export OPENAI_API_KEY="your-api-key-here"
  ```

  ```bash Anthropic theme={null}
  export ANTHROPIC_API_KEY="your-api-key-here"
  ```

  ```bash Google theme={null}
  export GOOGLE_API_KEY="your-api-key-here"
  ```
</CodeGroup>

## Your First Agent

Create a simple agent that maintains conversation history:

```python theme={null}
from egregore import Agent

# Create an agent with OpenAI's GPT-4
agent = Agent(provider="openai:gpt-4")

# Make your first call
response = agent.call("Hello! What's the weather like?")
print(response)

# The agent maintains context automatically
response = agent.call("What did I just ask you about?")
print(response)  # Agent remembers the previous question
```

<Tip>
  The agent automatically manages context history using PACT's depth system. Previous messages are pushed back through ODI (Overlap Demotion Invariant) as new turns are added.
</Tip>

## Using Scaffolds for Memory

Add persistent memory to your agent with the built-in notes scaffold:

```python theme={null}
from egregore import Agent
from egregore.core.context_scaffolds import InternalNotesScaffold

# Create scaffold for persistent notes
notes = InternalNotesScaffold()

# Create agent with scaffold
agent = Agent(
    provider="openai:gpt-4",
    scaffolds=[notes]
)

# The agent now has access to note-taking tools
response = agent.call(
    "Remember that my favorite color is blue. "
    "Also, I prefer working in the mornings."
)

# Later in the conversation...
response = agent.call("What do you know about my preferences?")
# Agent can retrieve notes from its persistent memory
```

## Streaming Responses

Get real-time responses as they're generated:

```python theme={null}
from egregore import Agent

agent = Agent(provider="openai:gpt-4")

# Stream the response
for chunk in agent.stream("Write a poem about AI"):
    print(chunk, end="", flush=True)
```

## Context Operations

Manipulate context precisely using PACT coordinates:

```python theme={null}
from egregore import Agent
from egregore.core.context_management import TextContent

agent = Agent(provider="openai:gpt-4")

# Insert a persistent reminder at system depth
reminder = TextContent(content="Always be concise and helpful.")
agent.context.pact_insert("d-1,0", reminder)

# The reminder persists across all turns
response = agent.call("Explain quantum computing")
# Response will be concise due to the system-level reminder
```

## Using Tools

Add custom tools to your agent:

```python theme={null}
from egregore import Agent

def get_weather(location: str) -> str:
    """Get the current weather for a location."""
    # In reality, you'd call a weather API
    return f"The weather in {location} is sunny, 72°F"

# Create agent with custom tool
agent = Agent(
    provider="openai:gpt-4",
    tools=[get_weather]
)

# Agent can now use the weather tool
response = agent.call("What's the weather in San Francisco?")
print(response)
```

## Hooks for Observability

Monitor and modify agent behavior with hooks:

```python theme={null}
from egregore import Agent

agent = Agent(provider="openai:gpt-4")

# Add a hook to log all tool calls
@agent.hooks.tool.pre_call
def log_tool_call(ctx):
    print(f"🔧 Calling tool: {ctx.tool_name}")
    print(f"   Parameters: {ctx.parameters}")

@agent.hooks.tool.post_call
def log_tool_result(ctx):
    print(f"✅ Tool result: {ctx.tool_result}")

# Tool calls will now be logged
response = agent.call("What's the weather in NYC?")
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="book" href="/core-concepts/overview">
    Learn about PACT architecture
  </Card>

  <Card title="Context Management" icon="layer-group" href="/core-concepts/context-management">
    Master the context tree
  </Card>

  <Card title="Scaffolds" icon="hammer" href="/features/scaffolds/overview">
    Build persistent memory systems
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/features/workflows/overview">
    Orchestrate multi-agent systems
  </Card>
</CardGroup>

## Common Patterns

### Multi-turn Conversation

```python theme={null}
agent = Agent(provider="openai:gpt-4")

# Context is automatically managed
agent.call("My name is Alice")
agent.call("I like Python programming")
agent.call("What do you know about me?")
# Agent remembers: name and Python preference
```

### Temporary Context with TTL

```python theme={null}
from egregore.core.context_management import TextContent

agent = Agent(provider="openai:gpt-4")

# Add a reminder that expires after 3 turns
reminder = TextContent(content="User is in a hurry", ttl=3)
agent.context.pact_insert("d0,1", reminder)

# Reminder available for 3 turns, then automatically removed
```

### Async Support

```python theme={null}
import asyncio
from egregore import Agent

async def main():
    agent = Agent(provider="openai:gpt-4")

    # Async call
    response = await agent.acall("Hello!")

    # Async streaming
    async for chunk in agent.astream("Tell me a story"):
        print(chunk, end="", flush=True)

asyncio.run(main())
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="ImportError: No module named 'egregore'">
    Make sure you've installed the package:

    ```bash theme={null}
    pip install egregore
    ```
  </Accordion>

  <Accordion title="API Key Not Found">
    Set your provider's API key as an environment variable:

    ```bash theme={null}
    export OPENAI_API_KEY="your-key"
    ```

    Or pass it directly:

    ```python theme={null}
    agent = Agent(provider="openai:gpt-4", api_key="your-key")
    ```
  </Accordion>

  <Accordion title="Context Too Long Error">
    Use TTL to manage context size:

    ```python theme={null}
    # Components expire after N turns
    component = TextContent(content="temp data", ttl=5)
    agent.context.pact_insert("d0,1", component)
    ```
  </Accordion>
</AccordionGroup>

## Resources

* [Full API Reference](/api-reference/agent/overview)
* [Example Gallery](/examples/basic/hello-world)
* [PACT Specification](/architecture/pact-specification)
* [GitHub Repository](https://github.com/yourusername/egregore)

## What's Next?

Now that you have a basic agent running, explore:

1. **[Context Management](/core-concepts/context-management)** - Learn PACT coordinates and depth system
2. **[Scaffolds](/features/scaffolds/overview)** - Build custom persistent memory systems
3. **[Hooks](/features/hooks/overview)** - Add observability and custom logic
4. **[Workflows](/features/workflows/overview)** - Orchestrate multiple agents

Happy building! 🚀