Skip to main content

Quickstart Guide

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

Installation

pip install egregore

Setup API Key

Egregore supports 30+ AI providers. Set up your preferred provider’s API key:
export OPENAI_API_KEY="your-api-key-here"

Your First Agent

Create a simple agent that maintains conversation history:
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
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.

Using Scaffolds for Memory

Add persistent memory to your agent with the built-in notes scaffold:
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:
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:
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:
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:
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

Common Patterns

Multi-turn Conversation

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

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

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

Make sure you’ve installed the package:
pip install egregore
Set your provider’s API key as an environment variable:
export OPENAI_API_KEY="your-key"
Or pass it directly:
agent = Agent(provider="openai:gpt-4", api_key="your-key")
Use TTL to manage context size:
# Components expire after N turns
component = TextContent(content="temp data", ttl=5)
agent.context.pact_insert("d0,1", component)

Resources

What’s Next?

Now that you have a basic agent running, explore:
  1. Context Management - Learn PACT coordinates and depth system
  2. Scaffolds - Build custom persistent memory systems
  3. Hooks - Add observability and custom logic
  4. Workflows - Orchestrate multiple agents
Happy building! 🚀