DEV Community: Michael Flanagan

Bedrock Knowledge Bases with S3 Vectors: A [Preview] CDK Quickstart

Michael Flanagan — Tue, 26 Aug 2025 22:10:25 +0000

Introduction

I've been hanging out in the AWS ecosystem for a while, and one of the things I've enjoyed is how Bedrock Knowledge Bases give you a relatively turnkey way to stand up RAG pipelines without duct taping half a dozen services together. The catch has always been vector storage. Until now, your out-of-the-box choices were either OpenSearch (simple but pricey) or Aurora Serverless (flexible but configuration-heavy, even if it scales to zero).

In July '25, AWS dropped something new into preview: Amazon S3 Vectors. It's a native vector store designed to be dirt cheap (AWS claims up to 90% lower cost than other options) at the expense of some performance. Latencies are higher, but for many workloads, and especially experimentation or pre-production it should be "good enough." Right now S3 Vectors show up as an option when you create new Knowledge Bases in the console… there isn't an official L2 CDK construct yet.

Repository Link: Building Bedrock Knowledge Base w/S3 Vectors

Purpose

That's where this CDK construct comes in. I've put together a relatively simple but configurable stack that wires up:

An ingestion S3 bucket
A Bedrock Knowledge Base
An S3 Vectors bucket and index
The appropriate IAM scaffolding
A Lambda-based cleanup finalizer (so your teardown doesn't fail on dangling vector stores).

It's not fully L2 yet, because most of the S3 Vectors pieces are so fresh they still require AwsCustomResource with installLatestAwsSdk: true, and cleanup had to be loaded into a Lambda because CloudFormation deletes in the wrong order otherwise. Hopefully this all gets abstracted in a future CDK release, but for now this construct should give you a reproducible, low-cost way to deploy Knowledge Bases with S3 Vectors.

Value

Who's this for? Pretty much anyone who wants to explore Bedrock KBs without burning cash on infra you don't need yet:

Hobbyists and students: Can build and test RAG pipelines on your own dime without becoming an Aurora expert or burning a clean 100+ USD monthly on OpenSearch.
Indie devs and small teams: Can prototype workflows, test integrations, or demo features without a runaway AWS bill.
Enterprise teams: Can spin up a pre-production configuration for experimentation, then later environments can utilize the more performant OpenSearch, Pinecone, or Aurora without rewriting your app since Bedrock's KB API abstracts the vector store, so swapping later is always on the table without changes to the underlying code.

⚠️ One early caveat: if you expect to move beyond this pattern, it's better to bring your own S3 ingestion bucket. Knowledge Bases are bound to their vector stores, so changing later can be destructive.

Hit the ground running (Quickstart)

Beyond the usual AWS account + CDK bootstrap, there are two things you need squared away before deploying:

Region: As of preview (July '25), S3 Vectors are only available in: us-east-1,us-east-2,us-west-2,eu-central-1,ap-southeast-2
Embedding model: You must have access to an embedding model supported by Bedrock KBs. At time of writing, that means:
- Amazon Titan Text Embedding v2: supports 256, 512, or 1024 dimensions
- Amazon Titan Text Embedding v1: requires 1536 dimensions

If you try another model, ingestion will fail because the dimensions won't line up.

Deploy the Construct

Once you've cloned the repo and reviewed the props you might want to tweak (prefixes, parsing model, deletion behavior, etc.), you can go ahead and synth/deploy:

npm install   # or yarn/pnpm
cdk synth      # optional, to review the generated CloudFormation
# however, on first pass it'd good to get a view on what you're generating!
cdk deploy

On success you'll get stack outputs that look like:

KnowledgeBaseId
KnowledgeBaseArn
IngestionBucketName (upload docs here; defaults to docs/)
VectorBucketName / VectorIndexName

Add Documents

Now drop some content into the ingestion bucket. By default, that means s3:///docs/.

For my first test, I uploaded a handful of short Wikipedia pages about sauces (pipian, mole, béchamel) just to have something fun to query against.

Kick Off an Ingestion Job

Next, tell Bedrock to ingest what you just uploaded:

aws bedrock-agent start-ingestion-job \
  --knowledge-base-id $KB_ID \
  --data-source-id $DS_ID

Then poll until you see it complete:

aws bedrock-agent get-ingestion-job \
  --knowledge-base-id $KB_ID \
  --data-source-id $DS_ID \
  --ingestion-job-id $JOB_ID

You can also check the status in the AWS Console under Bedrock -> Knowledge Bases -> Ingestion Jobs.

Try a Simple Retrieval

Once the job is complete, you can run a retrieval-only query (no LLM wrapping):

aws bedrock-agent-runtime retrieve \
  --knowledge-base-id $KB_ID \
  --retrieval-query '{"text":"What is pipian sauce?"}' \
  --retrieval-configuration '{"vectorSearchConfiguration": {"numberOfResults": 3}}'

This will return raw document chunks with their source references.

Step Up to RAG (Retrieve-and-Generate)

Now let's try a full RAG cycle with an LLM on top:

aws bedrock-agent-runtime retrieve-and-generate \
  --input '{"text":"Summarize pipian sauce in two sentences"}' \
  --retrieve-and-generate-configuration "{
    \"type\": \"KNOWLEDGE_BASE\",
    \"knowledgeBaseConfiguration\": {
      \"knowledgeBaseId\": \"$KB_ID\",
      \"modelArn\": \"arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-sonnet-20240229-v1:0\",
      \"retrievalConfiguration\": {
        \"vectorSearchConfiguration\": { \"numberOfResults\": 3 }
      }
    }
  }"

If all goes well, you should see a short, generated answer based on your docs.

And just like that, you've got a working S3 -> S3 Vectors Knowledge Base on AWS. You can now hook it into workflows, wrap it with agents, or query it from your own code. If you stick around, the next sections cover some caveats and sharp edges that will save you pain down the line.

Considerations & Watchouts (Before You're Committed)

Vector Store Lock-In

Your Knowledge Base is glued to its vector store. You don't get to swap later so if you decide to move to OpenSearch, Pinecone, Aurora Serverless, etc, you're rebuilding and re-ingesting. Because of that, I'd strongly suggest bringing your own S3 ingestion bucket up front. That way if the KB has to go, your docs don't go with it.

Model + Dimension Choice

Same deal with models and dimensions: once you've set it, that's it. Titan v2 is flexible (256/512/1024), Titan v1 is locked at 1536. Change your mind later? You're tearing down the KB and index and starting over. The construct defaults to Titan v2 at 1024 if you don't care enough to pick.

Price vs. Performance

S3 Vectors is dirt cheap, and right now they're the cheapest vector store option AWS has, but the latency is slower. Both ingestion and retrieval take longer compared to OpenSearch or Aurora. For tinkering, prototyping, low-intensity apps, it's more than fine. But if you're building something latency-critical, you'll probably outgrow it.

S3 Vectors: sub-second retrieval
OpenSearch Serverless: low tens of ms retrieval
Aurora pgvector: low tens-of-ms

Preview Warnings

Don't forget this is still in preview. The APIs aren't final. Permissions are broad, SDK calls may shift, and if you start seeing weird errors about malformed API calls popping up out of nowhere, that's probably AWS changing things under the hood. I'm expecting to have to refactor this construct a bit before general release, so you'd likely need to do the same if you pull it into your ecosystem.

With all that in mind, you should be good to get off to the races! If you want the deeper details of why the construct is wired the way it is, hang around for the deep dive.

Deep Dive (Why the Construct Is Wired the Way It Is)

Custom Resources and Fresh APIs

The first thing you'll notice when you crack open the code: a bunch of AwsCustomResource blocks with installLatestAwsSdk: true. This is because S3 Vectors is so new the APIs aren't in the default Lambda runtime SDK yet. This is a preview-only issue, and it'll go away once S3 Vectors land in the managed SDK.

Small aside: running installLatestAwsSdk also plays funny with how roles get wired in. Instead of relying on CDK to attach roles cleanly, I had to drop in a couple of explicit inline policies to make sure those Lambdas could actually talk to the services. It's not pretty, but it keeps things working until AWS smooths this out.

Cleanup Lambda

Normal S3 buckets can't be deleted if they still have objects, and S3 Vector buckets/inxexes are no different. CloudFormation doesn't know that - it just tries to rip things out in reverse order and fails. To fix this, the construct wires in custom resources to delete the index before the bucket, and adds a cleanup Lambda to handle the Bedrock bits (DataSource + Knowledge Base) in the right sequence. On cdk destroy, the two work together so teardown finishes cleanly instead of leaving you with dangling vector stores or broken stacks.

Broad Permissions for Now

You'll also see some wide-open IAM statements, especially around s3vectors:*. That's because the preview only supports * scoping for data-plane actions. I would not reasonably be able to trust ARN targeting yet as the feature persists through preview. Expect this to tighten up after general release, but in the meantime it's "better working than broken."

Parsing Options

By default, ingestion just chunks and indexes your docs. But I wired in optional foundation model parsing: run the content through Claude Sonnet (or another model) with a customizable prompt before vectorization. This is off by default because it can rack up costs fast depending on the model. If you flip it on, make sure the model is enabled in your account/region and double-check permissions + spend expectations.

Preview Caveat

All of the above (the custom resources, cleanup Lambda, broad IAM, parsing options) are wired this way because we're in preview. Expect SDK upgrades, CDK L2 support (for S3 Vectors/indexes and the datasource), and tighter IAM to land over time. Again, I'll be watching and updating over time as viable, but if I miss an update feel free to keep me honest in the repo!

Conclusion (Where This Fits, Where It Doesn't)

At the end of the day, I'm putting out this construct to help folk out while full support is pending. It's here to give you the cheapest, cleanest path into experimenting with Bedrock Knowledge Bases while AWS does what they do to produce the release version of S3 Vectors in the SDKs & CDK. If you're a hobbyist, student, or small team, this is your way to get hands-on without torching a cloud budget. If you're an enterprise shop, this is the kind of thing you point at for prototyping, internal demos, and pre-production environments, knowing you'll likely jump to OpenSearch, Pinecone, or Aurora for production once latency and compliance start mattering more.

More to the point, it's not the right fit if you're building latency-critical apps where sub-100ms is non-negotiable, and you need stable, compliance-ready APIs today (S3 Vectors is still preview).

But it is the right fit if you want to understand what Bedrock KBs can do, tinker with your own docs, and start building muscle memory around RAG on AWS without burning dollars unnecessarily.

Feel free to take this for a spin, let me know how it goes. I'll be iterating this repo as the preview evolves, but real-world feedback is always best!

References

AWS Direct Docs

Community / Blog Posts

That's it! You've got the quickstart, the caveats, the guts, and the guardrails. Give it a whirl, and if you hit something weird (or find a sharper way to solve the cleanup/permissions pain points), toss an issue or PR in the repo. I'd love to keep this one honest as S3 Vectors matures.

From Scrolls to Scripts: Orchestrating Agents with Chronicles

Michael Flanagan — Wed, 11 Dec 2024 01:10:19 +0000

🏰 Embarking on the Next Chapter

In the previous installments of my AI adventure, we laid down the foundational stones of our grand project. We began by exploring the Documents—the core entities like Actors and Locations that populate our creative worlds. Then, we ventured into the realm of Agents, capable helpers designed to perform specific tasks and bring our documents to life.

However, these Agents, while powerful individually, lack a unifying narrative to coordinate their actions. This brings us to the next exciting phase: introducing Chronicles. Just as a storyteller weaves characters and events into a captivating narrative, Chronicles orchestrate our Agents, guiding them through complex workflows to achieve larger goals.

Quick Stop: Time for reality

As I said before, I come bearing gifts this is my repository for this project:
Codex of Agents

For some help to specifically get this initial version off the ground feel free to give this first step readme a read:
First Steps

Why Chronicles?

In AI and automation, managing individual tasks is just the beginning. To tackle more intricate challenges, we need a way to coordinate multiple Agents seamlessly. Chronicles serve as scripts that outline each Agent's role, the sequence of actions, and how data flows between them.

By orchestrating our Agents with Chronicles, we transform individual performances into a harmonious ensemble, where each member knows their part and contributes to the harmony of the whole.

Setting the Stage

In this post, we'll dive into the art of orchestrating Agents using Chronicles. We'll focus on a few illustrative examples to keep things clear and manageable. Through these scenarios, we'll see how Agents can be coordinated to perform complex tasks that would be challenging for them to handle individually.

Looking ahead, there's much more on the horizon. In the next set of paired posts, we'll explore:

🛠️ Building a More Resilient Serverless Architecture: We'll delve into designing an infrastructure that can gracefully handle the demands of our growing system, ensuring scalability and robustness.
📜 Expanding the Agent Codex: We'll work on building out our list of Agents, enriching our system's capabilities and paving the way for more sophisticated workflows.

But for now, let's focus on mastering the basics of orchestration with Chronicles. After all, every epic tale begins with a single chapter.

The Power of Names in Software Development

🌟 What's in a Name?
When building anything—be it a world for a tabletop game or a piece of software—the words we choose matter. Precise terminology isn't just about semantics; it's about clear communication and shared understanding.

Clarity and Communication

In coding, names are more than labels; they're guides that help us navigate complex systems. A well-chosen name illuminates purpose and intent, reducing confusion for anyone reading the code or documentation. Yet, finding the right names is surprisingly tough. It's a balancing act between technical accuracy and engaging descriptiveness.

Our Thematic Shift

✨ Embracing Storytelling Elements

To address these challenges, we've embraced storytelling elements in our project. Given my love for narratives, I've decided to infuse our work with a bit of fantasy flair. By adopting terms from storytelling, we're not just writing code—we're crafting an experience.

Introducing Our Cast

📜 Scribe: The master planner who crafts Chronicles—the blueprints that guide our Agents.
- 📖 Chronicles: Detailed plans outlining the steps our Agents will take to accomplish complex tasks.
  - 🔖 Chapters: Individual steps within a Chronicle, each representing a specific action.
🧭 Navigator: An Agent that adjusts Chronicles in response to changes.
🤖 Agents: Our trusty helpers who carry out the tasks detailed in the Chronicles.
🛠️ Implements: The tools our Agents use to perform their duties.

By framing our technical components within a storytelling context, we make the system more engaging and relatable. This consistent theme enhances understanding and fosters a stronger connection to the project.

(Note: The "Navigator" will be introduced in future posts when its role becomes relevant.)

To prevent confusion, I'll provide clear definitions whenever introducing a new concept going forward!

Understanding Orchestration in AI Systems

🔗 The Art of Coordination
In the realm of artificial intelligence, individual components can achieve impressive feats on their own. However, as tasks grow in complexity, these components need to work together harmoniously. This is where orchestration comes into play.

What is Orchestration?

Orchestration is the coordination of multiple Agents to achieve complex objectives that would be challenging for a single entity. It's about managing workflows, handling dependencies, and ensuring that each part of the system knows its role within the bigger picture.

Think of it as conducting an orchestra: each musician plays their instrument, but it's the conductor who ensures they all perform in harmony. Similarly, in AI systems, orchestration involves planning and overseeing the interactions between various Agents to execute a multifaceted task seamlessly.

Why Orchestration Matters

While single agents can perform specific tasks efficiently, they often hit limitations when confronted with more intricate challenges. Coordinating multiple agents allows us to:

Divide and Conquer: Break down complex goals into manageable, discrete tasks.
Leverage Specialization: Utilize the unique capabilities of different agents, each designed for specific functions.
Enhance Flexibility: Adapt to changing requirements by rearranging or swapping agents without disrupting the entire system.
Improve Reliability: Design systems that can handle failures gracefully by redistributing tasks among agents. In essence, orchestration is essential for building AI systems that are robust, scalable, and capable of tackling real-world problems with agility.

Designing Our Orchestration Strategy

🛠️ Crafting the Plan
With orchestration and our storytelling theme in place, let's delve into how we're implementing this strategy in our project.

Our Approach

At the heart of our strategy is the separation of planning and execution:

📜 Scribe: The master planner who composes Chronicles based on our goals.
🤖 Agents: Specialists who execute tasks specified in the Chronicles, using their Implements.

This division maintains a clean architecture where each component has a distinct responsibility, enhancing scalability and maintainability. The Scribe focuses on crafting adaptable high-level plans, while Agents concentrate on efficiently performing their designated tasks, guided by the detailed instructions within each Chapter.

Key Features of Chronicles

We're concentrating on the basics to keep things straightforward:

Chapters: Individual steps within a Chronicle, each representing a specific action.
Dependencies: Relationships between Chapters that determine execution order.

By defining clear dependencies, we control the flow of execution, ensuring that Agents perform their tasks in the correct sequence—crucial when certain actions rely on the results of previous steps.

Keeping It Simple

Our initial focus is on these core elements to establish a solid foundation. By mastering the fundamentals of orchestrating Agents with Chronicles, we set the stage for introducing more complex features down the line.

Looking Ahead

While we're starting with the essentials, there's plenty of room for growth. In future posts, we'll explore advanced capabilities such as:

Parallelism: Allowing multiple Chapters to be executed simultaneously when there are no dependencies between them.
Retries and Error Handling: Implementing mechanisms to handle failures gracefully and ensure the robustness of our system.
Dynamic Adjustments: Introducing the Navigator to adjust Chronicles in response to changes or new information.

By building upon the basics, we'll gradually enhance our system's capabilities without overwhelming complexity.

Architecture of Chronicles in Our System

🧩 Building the Blueprint
Let's delve into the architecture that brings our system to life, focusing on how Chronicles are structured and how they interact with our Agents and Implements.

Defining the Chronicle Structure

At the core of our system lies the Chronicle, the orchestrated plan that guides our Agents.

Components of a Chronicle

🔖 Chapters: Goal-driven actions assigned to specific Agents. Think of them as individual quests in our grand adventure.
🧩 Dependencies: Define the order and prerequisites for Chapter execution, maintaining logical flow.
⏳ Status Tracking: Both Chronicles and Chapters have statuses to indicate their progress through the workflow.

Data Structures

Here's how we represent Chronicles and Chapters in code:

type ChronicleStatus = 'created' | 'ready' | 'inProgress' | 'complete' | 'failed';
type ChapterStatus = 'created' | 'ready' | 'inProgress' | 'complete' | 'failed';

interface Chronicle {
  id: string;             // Unique identifier
  title: string;          // Human-readable title
  goal: string;           // Overarching objective
  status: ChronicleStatus; // Current state
  chapters: Chapter[];    // List of Chapters
}

interface Chapter {
  id: string;             // Unique identifier
  targetAgent: string;    // Responsible Agent
  goal: string;           // Specific objective
  status: ChapterStatus;  // Current state
  inputContext?: Record<string, any>;  // Required data
  outputContext?: Record<string, any>; // Resulting data
  dependencies?: string[];             // Prerequisites
}

Integration with Agents and Implements

📜 Scribe: Generates the Chronicle using LLM requests (e.g., AWS Bedrock's Converse API), transforming user goals into detailed plans.
🤖 Agents: Execute assigned Chapters, utilizing Implements to perform actions. They update the status and output context accordingly.
🛠️ Implements: Tools that empower Agents, such as database connectors or API clients, allowing Agents to focus on their tasks without worrying about underlying mechanics.

Integrating with Agents and Implements

Now that we have our Chronicles defined, let's see how they integrate with our Agents and Implements.

📜 Scribe

The Scribe plays a pivotal role in our architecture. Using Large Language Model (LLM) requests—specifically AWS Bedrock's Converse API calls—the Scribe generates the orchestrating Chronicles. It takes the user's goals and transforms them into a detailed plan that our Agents can execute.

Here's how the Scribe operates:

Input Processing: Receives a natural language prompt from the user or other input sources, which may include multiple tasks.
Chronicle Generation: Crafts a Chronicle with structured Chapters, assigning each to the appropriate Agent and defining goals, contexts, and dependencies.
Status Initialization: Sets the initial status of the Chronicle and its Chapters to created.
Preparation for Execution: Updates the status to ready once the Chronicle is fully defined and dependencies are mapped.

🤖 Agents

Agents are the executors of our Chronicles. Each Agent is responsible for one or more Chapters within a Chronicle. When an Agent receives a Chapter:

Reads the Goal: Understands the specific objective of the Chapter.
Checks Dependencies: Ensures all dependencies have been satisfied before proceeding.
Uses Implements: Leverages its tools (Implements) to perform the necessary actions.
Updates Status:
- Sets the Chapter status to inProgress at the start of execution.
- Upon completion, updates the status to complete and records any output in the outputContext.
- If an error occurs, updates the status to failed.
Output Sharing: The outputContext can be accessed by dependent Chapters, facilitating data flow between Agents.

🛠️ Implements

Implements are the tools that empower our Agents to perform their duties. They provide the capabilities required for executing each Agent's Chapters. Implements can include:

Database Connectors: For storing or retrieving data (e.g., DynamoDB operations).
API Clients: To interact with external services or APIs.
Utility Libraries: For tasks like data transformation, validation, or formatting.

By abstracting functionalities into Implements, we enable Agents to focus on their specific tasks without worrying about the underlying mechanics. This modularity enhances reusability and simplifies maintenance.

Example Workflow: Simple Chronicle Execution

🎭 Bringing It All Together
Now that we've laid out the architecture and roles within our system, it's time to see how everything works in practice. Let's walk through a simple yet illustrative example that showcases how the Scribe, Agents, and Implements collaborate to achieve a common goal.

Scenario Overview

Goal (from the user's prompt):

I need your help to create some new characters and a location for our game world. First, there's Elthien Pettlebloom, an elf ranger who loves the forest. She's an expert archer and is seeking revenge against the orcs who destroyed her village. Next, Thorgar Ironfist, a dwarf warrior. He's a master blacksmith, enjoys hearty ale, and is on a quest to find the legendary Hammer of Durin. Finally, we need the Misty Mountains, a treacherous mountain range filled with ancient mines, hidden dangers, and rumored to house a sleeping dragon.

Agents Involved:

📜 DocumentRequestHandlingScribe: Our Scribe specialized in handling document-related requests and ensuring data integrity.
🤖 ActorSubmissionAgent: Responsible for processing and submitting Actor documents.
🤖 LocationSubmissionAgent: Responsible for processing and submitting Location documents.
🤖 DocumentRelationshipMappingAgent: Handles mapping relationships within our relationship datastore. This Agent prefers to depend on the resolution of submission-related Agents to reduce executions.

Note: For those curious, I use the term Ancestry when referring to the types and origins of our characters—yes, I'm a big fan of Pathfinder 2nd Edition!

Our Scenario’s Chronicle

Upon receiving the user's prompt, the DocumentRequestHandlingScribe processes the input and generates the following Chronicle:

<chronicle>
  <chapter id="chapter-001">
    <targetAgent>ActorSubmissionAgent</targetAgent>
    <dependencies/>
    <goal>Process and submit the document for the character Elthien Pettlebloom.</goal>
    <context>
      <name>Elthien Pettlebloom</name>
      <ancestry>Elf</ancestry>
      <class>Ranger</class>
      <traits>
        <trait>Forest lover</trait>
        <trait>Expert archer</trait>
        <trait>Seeking revenge against orcs who destroyed her village</trait>
      </traits>
    </context>
  </chapter>
  <chapter id="chapter-002">
    <targetAgent>ActorSubmissionAgent</targetAgent>
    <dependencies/>
    <goal>Process and submit the document for the character Thorgar Ironfist.</goal>
    <context>
      <name>Thorgar Ironfist</name>
      <ancestry>Dwarf</ancestry>
      <class>Warrior</class>
      <traits>
        <trait>Master blacksmith</trait>
        <trait>Enjoys hearty ale</trait>
        <trait>On a quest to find the legendary Hammer of Durin</trait>
      </traits>
    </context>
  </chapter>
  <chapter id="chapter-003">
    <targetAgent>LocationSubmissionAgent</targetAgent>
    <dependencies/>
    <goal>Process and submit the document for the location Misty Mountains.</goal>
    <context>
      <name>Misty Mountains</name>
      <description>A treacherous mountain range filled with ancient mines, hidden dangers, and rumored to house a sleeping dragon.</description>
    </context>
  </chapter>
  <chapter id="chapter-004">
    <targetAgent>DocumentRelationshipMappingAgent</targetAgent>
    <dependencies>
      <dependency>chapter-001</dependency>
      <dependency>chapter-002</dependency>
      <dependency>chapter-003</dependency>
    </dependencies>
    <goal>Map relationships among the submitted characters and location in the relationship datastore.</goal>
    <context/>
  </chapter>
</chronicle>

Execution Flow

Let's step through how this Chronicle is executed within our system.

Scribe Generates the Chronicle
- The DocumentRequestHandlingScribe receives the user's prompt.
- Parses the prompt to identify entities (characters and location).
- Constructs the Chronicle with four Chapters, each assigned to the appropriate Agent.
- Sets the status of the Chronicle and all Chapters to "created".
Scribe Prepares the Chronicle for Execution
- Updates the status of the Chronicle to "ready".
- Sets the status of Chapters 1 to 3 to "ready" since they have no dependencies.
- Chapter 4 remains at "created" because it depends on the completion of the first three Chapters.
Agents Execute Chapters 1 to 3
- For each of Chapters 1 to 3:
- The assigned Agent retrieves the Chapter when its status is "ready".
- Updates the Chapter status to "inProgress".
- Agent Execution Pseudocode:

async function executeChapter(chapter: Chapter) {
  chapter.status = 'inProgress';
  try {
    const inputData = chapter.inputContext;

    // Augment the document using the style guide
    const augmentedData = applyStyleGuide(inputData);

    // Submit the document to DynamoDB (simulated)
    const documentId = await submitToDynamoDB(augmentedData);

    // Update the Chapter's output context with the document ID
    chapter.outputContext = { documentId };

    chapter.status = 'complete';
  } catch (error) {
    chapter.status = 'failed';
    // Handle error (e.g., log it, retry logic)
  }
}

For Chapters 1 and 2 (ActorSubmissionAgent):
- Processes the character data.
- Augments the data according to the style guide (e.g., ensuring required fields are present).
- Stores the Actor document in DynamoDB.
- Records the document ID in the outputContext.
For Chapter 3 (LocationSubmissionAgent):
- Processes the location data.
- Augments the data as per the style guide.
- Stores the Location document in DynamoDB.
- Records the document ID in the outputContext.
Scribe Updates Chapter 4 to Ready
- Once Chapters 1 to 3 are "complete", the Scribe (or a simple status-checking mechanism within the Scribe Lambda) updates Chapter 4's status to "ready".
DocumentRelationshipMappingAgent Executes Chapter 4
- The DocumentRelationshipMappingAgent retrieves Chapter 4.
- Updates the Chapter status to "inProgress".
- Agent Execution Pseudocode:

async function executeRelationshipMapping(chapter: Chapter, chronicle: Chronicle) {
  chapter.status = 'inProgress';
  try {
    // Gather outputs from dependencies
    const dependencyOutputs = chapter.dependencies?.map(depId => {
      const depChapter = chronicle.chapters.find(ch => ch.id === depId);
      return depChapter?.outputContext;
    });

    // Process relationships
    const relationships = mapRelationships(dependencyOutputs);

    // Optionally store relationships
    await storeRelationships(relationships);

    chapter.status = 'complete';
  } catch (error) {
    chapter.status = 'failed';
    // Handle error
  }
}

Functionality:
- Collects the document IDs from Chapters 1 to 3.
- Identifies potential relationships between the characters and the location.
- For example, associating Thorgar Ironfist with the Hammer of Durin if it exists in the datastore.
- Updates the relationship datastore accordingly.
- Marks the Chapter as "complete" upon success.
Completion of the Chronicle
- Once all Chapters are "complete", the Chronicle's status is updated to "complete".
- The workflow is successfully executed, and the new characters and location are now part of the game world, with relationships mapped.
- Code Snippets
- Here's a simplified version of how this might look within our Scribe Lambda Function:

export const handler = async (event: any) => {
  // Assume event contains the user's prompt  const userPrompt = event.userPrompt;
  // Step 1: Generate the Chronicle  const chronicle = generateChronicle(userPrompt);
  // Step 2: Prepare Chapters 1-3  chronicle.chapters.forEach(chapter => {
    if (!chapter.dependencies || chapter.dependencies.length === 0) {
      chapter.status = 'ready';
    }
  });
  // Step 3: Execute Chapters 1-3  for (const chapter of chronicle.chapters) {
    if (chapter.status === 'ready') {
      await executeChapter(chapter);
    }
  }
  // Step 4: Update Chapter 4 to Ready  const chapter4 = chronicle.chapters.find(ch => ch.id === 'chapter-004');
  if (chapter4 && chapter4.dependencies?.every(depId => {
    const depChapter = chronicle.chapters.find(ch => ch.id === depId);
    return depChapter?.status === 'complete';
  })) {
    chapter4.status = 'ready';
    await executeRelationshipMapping(chapter4, chronicle);
  }
  // Step 5: Update Chronicle Status  if (chronicle.chapters.every(ch => ch.status === 'complete')) {
    chronicle.status = 'complete';
  } else {
    chronicle.status = 'failed';
  }
  // Return the final status  return {
    statusCode: 200,
    body: JSON.stringify({
      message: 'Chronicle execution complete',
      chronicleStatus: chronicle.status,
    }),
  };
};

Notes on Execution

All execution occurs within the Scribe Lambda function, simplifying our architecture for this example.
Status Management: We use the status fields to control the flow of execution and handle dependencies.
Error Handling: If any Chapter fails, its status is set to "failed", and appropriate error handling can be implemented (e.g., retries, logging).
Data Flow: The outputContext of Chapters allows us to pass data between Agents, crucial for dependent tasks like relationship mapping.

Implements in Action

applyStyleGuide: A utility function (Implement) used by Agents to ensure that the data adheres to our predefined style guidelines.
submitToDynamoDB: An Implement that abstracts the process of storing documents in DynamoDB.
mapRelationships: Used by the DocumentRelationshipMappingAgent to establish connections between entities.
storeRelationships: An Implement for persisting relationship data.

Outcome

By the end of this workflow:

Elthien Pettlebloom and Thorgar Ironfist are added to our game world's database as new characters.
The Misty Mountains becomes part of our location data.
Relationships among the characters and location are established, enriching the game's narrative fabric.

This example demonstrates how our system orchestrates multiple Agents to achieve a complex goal, all within a single execution flow. It showcases the power of the Chronicle structure, the coordination of Agents, and the utility of Implements.

In the next section, we'll reflect on how this workflow highlights the strengths of our orchestration strategy and discuss potential enhancements for future iterations. The journey doesn't end here—there are many more adventures to embark upon as we continue to build and refine our system.

Highlighting the Potential of Chronicles

🌟 Unleashing the Power of Coordination
By now, we've seen how Chronicles serve as the orchestrators of our Agents, guiding them through complex tasks with ease. But what makes Chronicles truly shine in our system? Let's delve into the benefits that Chronicles bring to the table and how they set the stage for future enhancements.

Benefits of Using Chronicles

Scalability

One of the standout advantages of utilizing Chronicles is the inherent scalability they offer.

Effortless Expansion: Need to add a new feature or incorporate another Agent? With Chronicles, it's as simple as writing a new Chapter and assigning it to the appropriate Agent.
Parallel Development: Multiple Chronicles can be crafted and executed simultaneously, allowing different teams or Agents to work on various aspects of the project without stepping on each other's toes.

Maintainability

A well-structured Chronicle makes maintaining and updating our system a breeze.

Clear Structure: Each Chapter within a Chronicle is a self-contained unit with a specific goal, making it easier to identify where changes need to be made.
Simplified Debugging: If something goes awry, the status tracking within Chronicles and Chapters helps pinpoint exactly where the issue occurred, reducing downtime and frustration.

Flexibility

Perhaps one of the most exciting aspects is the flexibility that Chronicles introduce.

Adaptive Agents: Agents can interpret and execute Chapters based on the context provided, allowing for dynamic responses to varying inputs or situations.
Easy Reconfiguration: Want to change the flow of tasks? Adjusting dependencies or reordering Chapters in a Chronicle allows us to reshape the workflow without extensive rewrites.

Setting the Stage for Future Enhancements

Our journey doesn't stop here. Chronicles open up a world of possibilities for more sophisticated workflows and integrations.

Complex Workflows

Intricate Dependencies: Future Chronicles can incorporate more complex dependency structures, enabling the modeling of intricate processes that mirror real-world scenarios.
Conditional Logic: Introducing conditions within Chapters can allow Agents to make decisions on the fly, further enhancing the system's responsiveness.

Integration with the Agent Codex

Expanding the Roster: As we build out our Agent Codex, we'll introduce new Agents with specialized skills, broadening the system's capabilities.
Enhanced Functionality: With a richer set of Agents and Implements, Chronicles can orchestrate more diverse and powerful workflows, from data analytics to real-time decision-making.

Next Steps

🚀 Charting the Path Forward
With the foundational pieces in place, it's time to look ahead at what's on the horizon for our project. The journey of building this system is akin to an epic tale, and the next chapters promise to be just as thrilling.

Exploring Resilient Serverless Architecture

In the upcoming posts, we'll dive into designing a more robust serverless architecture.

Scalability at Scale: We'll explore how to ensure our system can handle increased load without breaking a sweat.
State Management: Managing state in a distributed, serverless environment presents unique challenges. We'll tackle these head-on, implementing solutions that keep our system responsive and reliable.

Building Out the Agent Codex

Our Agents are the heart of the system, and it's time to expand their ranks.

New Agents and Implements: We'll introduce a host of new Agents, each bringing unique capabilities to the table. From data processors to AI-driven decision-makers, the possibilities are vast.
Enhanced Flexibility: With more Agents at our disposal, Chronicles can orchestrate increasingly complex tasks, opening doors to functionalities we haven't yet imagined.

By focusing on these areas, we're setting ourselves up for a future where our system isn't just functional—it's exceptional.

Conclusion

📝 Wrapping Up Our Journey
As we close this chapter, let's reflect on the ground we've covered and look forward to the adventures yet to come.

Recap of Key Takeaways

The Power of Chronicles: We've seen how Chronicles serve as the orchestrators, uniting our Agents to achieve complex goals efficiently.
Thoughtful Naming Matters: By embracing storytelling elements, we've made our system more engaging and easier to understand, demonstrating that clarity and creativity can go hand in hand.
Simplicity in Action: Even a simple Chronicle can coordinate multiple Agents to perform tasks that would be challenging to handle individually.

Invitation for Engagement

I encourage you to explore the repository and experiment with the code. Whether you're a seasoned developer or just starting out, there's a place for you in this journey.

Try It Out: Clone the repo, run the examples, and see how Chronicles and Agents work together firsthand.
Share Your Thoughts: Your feedback is invaluable. Feel free to open issues, suggest enhancements, or share your experiences.

Looking Forward

The story doesn't end here—it's just beginning. Stay tuned for our next installment, where we'll dive into advanced orchestration mechanisms and expand our Agent Codex, setting the stage for even more ambitious projects.

References (The Big One)

GitHub Repository: Codex of Agents

Building the Backbone: Entities Part 2, Agent

Michael Flanagan — Tue, 12 Nov 2024 02:04:27 +0000

The Best Way to Start a Story Is from the Beginning

In my previous post, I laid the foundations for our core structure—defining the fundamental entity structure and fleshing out the Document entity that underpins our system. With this groundwork in place, I'm excited to dive into defining the Agent as an entity.
However, I can't jump straight into that just yet. While the concepts of documents and their derived types might make intuitive sense, it's important to cover some basic concepts around Agents (a common shorthand for AI Agent).
Once I've laid out these concepts, I'll be able to define the related entities in this context, the basic actions needed for these entities, and finally present the full picture for this page of our codex.

Agents, Their Pieces and Their Wholes

To get started, AWS describes agents as:

"An artificial intelligence (AI) agent is a software program that can interact with its environment, collect data, and use the data to perform self-determined tasks to meet predetermined goals." - Link

As that implies, agents are expected to perform actions much like a "normal human" might, given the same information available to them. The most prolific agents in distribution are the myriad AI chatbots that have emerged in recent years, with several "out-of-the-box" chatbots capable of evaluating files, searching the internet, and more.
Agents reveal much more of their potential when we take things a step further—allowing these programs access to other systems via APIs or similar methods. By providing them with context-specific datasets, we enable agents to achieve their goals significantly more accurately.
To accomplish this our Agents will use:

Large Language Models (LLM): These will translate my instructions, context, and the options available into a plan of action.
Tool Use/Function Calling: This enables the agent to execute its plan of action by reaching out to APIs, datasets, or even executing code on its own.
Agent Orchestration: While individual agents are powerful, orchestrating multiple agents amplifies that power, allowing them to achieve goals that are too intricate for a single agent to handle. Think of orchestration as a collaborative effort where each agent performs specialized roles, enabling them to tackle more complex problems by working in unison. This coordination—whether managing story details in a campaign or automating multifaceted workflows—opens doors to streamlined and sophisticated outcomes that one agent alone couldn't accomplish.

Let's delve a little deeper.

LLMs, Mind in the Model

At the heart of an agent's capabilities lies the Large Language Model (LLM). These models are trained on vast amounts of text data, enabling them to understand and generate human-like language. In my system, the LLM acts as the "brain" of the agent, interpreting instructions, understanding context, and formulating plans.

How LLMs Function in the Agent:

Interpreting Instructions: The LLM processes my input—be it a command, a question, or a narrative prompt—and determines the underlying intent.
Contextual Understanding: By leveraging the context-specific datasets I provide (like campaign notes or world-building documents), the LLM can generate responses that are highly relevant and tailored to the specific scenario.
Generating a Plan of Action: Based on the instructions and context, the LLM devises a sequence of steps or actions that the agent should take to achieve the desired goal.

Tools, Body of Work

While the LLM provides the cognitive processing, the agent needs tools to interact with the environment and execute tasks. These tools are like the "hands" and "feet" of the agent, enabling it to perform actions beyond just thinking.

Key Tools and Functions:

API Access: Allows the agent to retrieve data from or send commands to external services. For example, fetching the latest game notes from a database or updating a character's status.
Dataset Interaction: Enables the agent to read from and write to specific datasets, ensuring it has the most up-to-date information and can record new insights. Code Execution: Grants the agent the ability to run code snippets, automate scripts, or perform computations necessary for its tasks.
External Integrations: Tools that let the agent interface with other platforms, like sending messages on communication apps or updating documents.

By equipping agents with these tools, they can move from planning to action, effectively bridging the gap between decision-making and execution.

Orchestration, Living in a Society

As tasks grow in complexity, a single agent may not suffice. Orchestration comes into play by coordinating multiple agents, each with specialized roles, to work together harmoniously.

Benefits of Agent Orchestration:

Specialization: Agents can focus on what they do best. One might handle data retrieval, another manages analysis, and a third focuses on content generation.
Parallel Processing: Tasks can be divided among agents to be executed simultaneously, improving efficiency.
Collaboration: Agents can share results and insights with each other, enhancing the overall capabilities of the system.

Real-World Application: LLM-as-a-Judge

Imagine a scenario where an Agent acts as a "judge" to evaluate and score the quality of outputs generated by other agents, enabling a systematic and unbiased approach to selecting the best result.

Basic Orchestration: Start with a simple setup where one agent generates content—let’s say a product description. The LLM-as-a-Judge agent then reviews this description against specific criteria, such as clarity or conciseness, and assigns it a score along with constructive feedback. This basic orchestration not only improves content quality but also provides transparent reasoning that can be used for further refinement.
Multi-Agent Evaluation: Now, consider a more complex situation where multiple agents produce outputs—say, three agents tasked with generating alternative headlines for a marketing campaign. The LLM-as-a-Judge then evaluates each headline, selecting the one that best meets a particular metric, such as engagement potential or brand alignment. In this setup, the judge agent doesn’t just rate outputs but actively decides which submission is the "winner," streamlining decision-making and ensuring a standard of quality.
Scalable Orchestration for Diverse Outputs: In an even more advanced use case, orchestration could involve multiple "judged" agents working on different aspects of a task. For example, imagine a content creation pipeline where one agent generates text, another designs accompanying visuals, and a third drafts social media captions. The LLM-as-a-Judge evaluates these outputs based on coherence and alignment with campaign goals, selecting the best combination to form a cohesive final piece. This layered orchestration maximizes output quality by coordinating specialized agents and aligning their work with overarching objectives.

Defining Agents as Entities

Now that we have a clearer understanding of what our agents need to accomplish and a glimpse into how they operate, let's discuss the actual business entity. We'll be defining our Agent entity through its own instructions and the Tool sub-entities it can access to fulfill these instructions.

The Agent

The eponymous star in our Codex of Agents, the Agent entity is the cornerstone of our system. When one of our agents is invoked, it generates a Plan. During the plan's evaluation, different tools are called, various LLM models are utilized, and potentially other agents are orchestrated to meet the requirements for the agent's execution.

Properties:

Capabilities: A list of actions or tools the agent can utilize, defining what it can do within the system.
Context: Stores any context-specific information the agent needs to function effectively, such as current tasks or relevant data.
State: Keeps track of the agent's current status or any intermediate data during operations.

Methods:

generatePlan(instruction): Uses the LLM to create a plan of action based on the given instruction and context.
- To Be Continued...: You may notice the Plan type outlined isn't delved into in this document, nor are these methods around the plan / integrations actually fully defined. We'll get to that a post or two down the road so we can fully delve into Orchestration.
executePlan(plan): Carries out the steps defined in the plan using available tools.
interactWithAgent(otherAgent): Facilitates communication and collaboration with other agents when orchestrated.
updateState(newState): Updates the agent's internal state based on actions taken or new information received.
Sample Code Snippet:

import { Entity } from './entity';
import { Tool } from './tool';
import { DocumentType as _DocumentType } from '@smitty/types';

interface AgentProps {
  capabilities: Tool[];
  context: any;
  state: any;
}

class Agent extends Entity<AgentProps> {
  constructor(props: AgentProps) {
    super(props);
    // Additional initialization if needed
  }

  generatePlan(instruction: string): Plan {
    // Utilize LLM to generate a plan based on the instruction and context
    return llm.generatePlan(instruction, this.props.context);
  }

  executePlan(plan: Plan): void {
    // Execute each step in the plan using available tools
  }

  updateState(newState: any): void {
    this.props.state = newState;
  }

  // Additional agent-specific methods...
}

The Tools

Tools are standardized components that empower agents to perform specific actions. They follow a consistent structure, making them easily integrable and reusable across different agents.

Standard Structure of Tools

Name: A unique name for the tool, should be somewhat human readable so plans around the tool may be made easier.
Description: Explains what the tool does, aiding the agent in selecting the appropriate tool for a task.
Input Schema: Defines the expected input parameters, ensuring the tool is used correctly.
Parameters (Params): Specific configurations or settings required by the tool, allowing customization for different contexts.

This design is influenced by guidelines from Anthropic's Tool Use and AWS's Bedrock Tool Documentation, which emphasize the importance of clear interfaces for tool integration.

Base Tool Interface

interface ToolInput {
  // Define the structure of the input required by the tool
}

interface ToolParams {
  // Define any additional parameters or configurations
}

abstract class Tool<TInput extends ToolInput, TParams extends ToolParams> {
  name: string;
  description: string;
  params: TParams;

  constructor(name: string, description: string, params: TParams) {
    this.name = name;
    this.description = description;
    this.params = params;
  }

  abstract execute(input: TInput): any;
}

DynamoDB Tool

As an example, let's explore a tool that allows agents to interact with DynamoDB to retrieve items based on a given key or composite key.

Key Features:

Configurable Parameters: Includes the table name and key schema (key names and types) necessary for querying DynamoDB.
Input Definition: Specifies the inputs required to perform the operation, such as key values.
Execution Logic: Implements the execute method to perform the actual DynamoDB query.

Implementation:

import { DocumentType as _DocumentType } from '@smitty/types';
import AWS from 'aws-sdk';
import { Tool } from './tool';

interface DynamoDBToolInput extends ToolInput {
  key: { [key: string]: any };
}

interface DynamoDBToolParams extends ToolParams {
  tableName: string;
  keySchema: { [key: string]: string }; // Key names and their data types
}

class GetDynamoDBItemTool extends Tool<DynamoDBToolInput, DynamoDBToolParams> {
  constructor(params: DynamoDBToolParams) {
    const inputSchema: _DocumentType = {
      type: 'object',
      properties: {
        key: {
          type: 'object',
          properties: Object.fromEntries(
            Object.entries(params.keySchema).map(([keyName, keyType]) => [
              keyName,
              { type: keyType },
            ])
          ),
          required: Object.keys(params.keySchema),
        },
      },
      required: ['key'],
    };

    super(
      'GetDynamoDBItem',
      'Retrieves an item from DynamoDB based on the provided key.',
      params,
      inputSchema
    );
  }

  async execute(input: DynamoDBToolInput): Promise<any> {
    // Validate input against inputSchema if necessary

    // Use AWS SDK to query DynamoDB
    const dynamoDB = new AWS.DynamoDB.DocumentClient();
    const params = {
      TableName: this.params.tableName,
      Key: input.key,
    };
    try {
      const data = await dynamoDB.get(params).promise();
      return data.Item;
    } catch (error) {
      // Handle error
      throw error;
    }
  }
}

When an agent needs to retrieve data from DynamoDB, it can utilize this tool by providing the necessary input, and the tool handles the rest.

Example Instantiation:

const usersKeySchema = {
  userId: 'string',
};

const getUserTool = new GetDynamoDBItemTool({
  tableName: 'UsersTable',
  keySchema: usersKeySchema,
});

const input = {
  key: { userId: '12345' },
};

getUserTool.execute(input).then(user => {
  console.log('User:', user);
}).catch(error => {
  console.error('Error retrieving user:', error);
});

AgentHandoff Tool

The AgentHandoffTool embodies the concept of orchestration within our system. It enables an agent to delegate tasks or pass context to another agent seamlessly.

Functionality:

Defines Target Agent(s): Specifies the key or identifier of the agent(s) to hand off to.
Execution Logic: Through the execute method, the tool facilitates passing the current context and appropriate input to the designated agents.
Seamless Transition: Allows agents to collaborate by handing off tasks without interrupting the workflow. ##### Implementation:

import { DocumentType as _DocumentType } from '@smitty/types';
import { Tool } from './tool';
import { Agent } from './agent';
import { AgentRepository } from './agentRepository';

interface AgentHandoffInput extends ToolInput {
  context: any;
  input: any;
}

interface AgentHandoffParams extends ToolParams {
  targetAgentIds: string[]; // IDs of the agents to hand off to
}

class AgentHandoffTool extends Tool<AgentHandoffInput, AgentHandoffParams> {
  constructor(params: AgentHandoffParams) {
    const inputSchema: _DocumentType = {
      type: 'object',
      properties: {
        context: { type: 'object' },
        input: { type: 'object' },
      },
      required: ['context', 'input'],
    };

    super(
      'AgentHandoff',
      'Hands off the current task and context to specified agent(s).',
      params,
      inputSchema
    );
  }

  execute(input: AgentHandoffInput): any {
    // Validate input against inputSchema if necessary

    // Logic to pass context and input to target agents
    for (const agentId of this.params.targetAgentIds) {
      const targetAgent = AgentRepository.getAgentById(agentId);
      if (targetAgent) {
        targetAgent.receiveHandoff(input.context, input.input);
      } else {
        // Handle agent not found scenario
        console.error(`Agent with ID ${agentId} not found.`);
      }
    }
    return { status: 'Handoff Complete' };
  }
}

Example Instantiation:

const agentHandoffTool = new AgentHandoffTool({
  targetAgentIds: ['agent-abc123', 'agent-def456'],
});

const handoffInput = {
  context: { sessionId: 'session-789' },
  input: { task: 'Process user feedback' },
};

agentHandoffTool.execute(handoffInput);

Closing Thoughts

Phew! That was a bit dive into our agents and tools. Like characters in a story finding their roles, it's good to see our entities finding their parts in this project. We've set a solid foundation, and I can't wait to see how these agents will interact and evolve as we continue this journey.

What's Next

In our next installment, we'll embark on the adventure of defining Plans—the blueprints that guide our agents' actions. We'll explore how these plans function, how they're crafted, and how they orchestrate the harmony between agents and tools. Plus, we'll start following along with the code for this project.

Stay tuned; the plot is just getting interesting!

Helpful References

Evidently AI's LLM-as-a-Judge Guide: LLM-as-a-Judge
AWS AI Agents Overview: AWS AI Agents
Anthropic Tool Use: Tool Use with Anthropic's Models
Bedrock Tool Use: Tool Use with AWS Bedrock

Building the Backbone: Entities Part 1, Document

Michael Flanagan — Sat, 02 Nov 2024 23:11:54 +0000

🏗️ Laying the Foundation: Embracing Worldbuilding and Game Mastery

In my previous post, I embarked on an AI journey to tackle the complexities of managing creative projects, particularly in the realm of tabletop games, cooking, and note management. I'm excited to say that the direction for implementing this document management framework will be in the realm of the fantastical, specifically in the realm of world building and game mastery.

Today, I'm excited to dive deeper into the technical side, focusing on defining the core Document type that will serve as the backbone of this system.

Why go down this path?

As a game master and worldbuilder, I deal with an ever-growing web of characters, locations, lore, and countless other elements that make up the worlds I enjoy with my friends. However, managing all this information can be overwhelming, and details can easily get lost or be obfuscated unless you're an ace power user of your tool of choice.

In short, I wanted to create a system that not only organizes this data efficiently but also allows for scalability, flexibility as my worlds expand, and lets my players and friends have an easier time reviewing and relating to the world they're playing in.

To start, by implementing a robust Document type that extends from a generic Entity base class, I can ensure that all pieces of content in my system are treated uniformly, allowing for consistent handling of metadata, relationships, and domain events. This design choice aligns with a few of the principles from Clean Architecture and Domain-Driven Design, providing a strong foundation for future growth.

📚 Understanding the Core: `Entity` and `Document` Classes

At the heart of my system lies the Entity base class. This generic class provides the foundational properties and methods common to all entities in the system. By extending Entity, the Document class inherits these essential features and adds document-specific properties and behaviors.

Entity Base Class

Purpose: Provides unique identification, domain event handling, and common functionalities for all entities.
Properties:
- _id: Unique identifier (UUID).
- _created: Timestamp of creation.
- _updated: Timestamp of the last update.
- props: Properties specific to the derived class.
Methods:
- Domain event handling (addDomainEvent, clearDomainEvents, etc.).
- Validation and timestamp management.

export abstract class Entity<T> {
  private readonly _id: string;
  private readonly _created: string;
  private _updated: string;
  protected props: T;
  private _domainEvents: DomainEvent[] = [];

  constructor(props: T, id?: string, created?: string, updated?: string) {
    this._id = id ? id : uuid();
    this._created = created ? created : new Date().toISOString();
    this._updated = updated ? updated : new Date().toISOString();
    this.props = {
      ...props,
      id: this._id,
      created: this._created,
      updated: this._updated,
    };
  }

  // Domain event methods, getters, and setters...
}

Document Class (Extends Entity)

Purpose: Serves as the base class for all document types in the system.
Additional Properties (within props):
- title: The document's title.
- content: Main body of the document.
- metadata: Collection of key-value pairs for additional context.
Methods:
- Document-specific behaviors and utilities.

interface DocumentProps {
  title: string;
  content: string;
  metadata: Map<string, any>;
  relationships: Relationship[];
  // Other properties as needed
}

class Document extends Entity<DocumentProps> {
  constructor(props: DocumentProps) {
    super(props);
    // Additional initialization if needed
  }

  // Document-specific methods...
}

🔍 Defining Actors and Locations as Specialized Documents

In these early days, I need to determine the key entities required to get this project moving, knowing that there will be more to add as the project evolves. And in this context, two are relatively obvious: Actor and Location. By inheriting from Document, they gain all the base functionality and can add their own specific properties and methods, and give a good view into how the framework will need to adapt as more complex relationships eventually get made.

Actor Class (Extends Document)

Purpose: Represents a person or creature within the game world.
Additional Properties (within props):
- name: { full name, given name, etc.}
- ancestry: the ancestral origins of the actor, could be Human, Orc, Dragon, etc.
- relationships: Connections to other entities.

interface ActorProps extends DocumentProps {
  name: ActorName,
  ancestry: ActorAncestry,
}

class Actor extends Document {
  constructor(props: ActorProps) {
    super(props);
    // Additional initialization if needed
  }

  // Actor-specific methods...
}

Location Class (Extends Document)

Purpose: Represents a place within the game world.
Additional Properties (within props):
geography: Details about terrain, climate, etc.

interface LocationProps extends DocumentProps {
  geography: string;
}

class Location extends Document {
  constructor(props: LocationProps) {
    super(props);
    // Additional initialization if needed
  }

  // Location-specific methods...
}

🔗 Class Relationships

✏️ Why This Implementation?

Choosing this structure offers several advantages:

Uniform Handling of Entities: By having all classes extend from Entity, we ensure that core functionalities like identity management and domain event handling are consistent across the system.

Extensibility: New document types can be added easily by extending Document. This makes the system flexible and adaptable to future needs.

Separation of Concerns: Entity handles generic entity behavior, Document handles document-specific behavior, and domain-specific classes like Actor and Location add their unique attributes.

Alignment with Clean Architecture: This design promotes a clear separation between domain models and other layers, enhancing maintainability and scalability.

🤔 Planning for Agents as Future Entities

Although agents are not yet part of the user-facing interface, I'm designing the system so that agents can be treated as entities in the future. By extending Entity, agents can be managed similarly to other entities, allowing for:

User Customization: Users could fine-tune agents to suit their needs.
Unified Management: Consistent handling of entities simplifies the system architecture.
Future-proofing: Preparing for agents as entities now avoids significant refactoring later. 🤖 Note: In our next post ("Entities Part 2, Agents"), I'll delve deeper into how agents fit into this architecture.

🔄 Delving into the Code: Understanding Entity

The Entity class is crucial to the system's architecture. Here's a closer look at its implementation:

Generics: Using generics () allows Entity to be flexible with the properties (props) it holds.

Domain Events: Entity includes methods to manage domain events, which are important for maintaining consistency and handling side effects in a decoupled manner.

Validation: The class includes a validate method to ensure that the properties meet the defined schema.

public addDomainEvent(eventDetails: ICreateDomainEvent): void {
  if (eventDetails.eventSchema) {
    validate(eventDetails.eventSchema, eventDetails.event);
  }

  const event: DomainEvent = {
    source: eventDetails.source,
    eventName: eventDetails.eventName,
    event: eventDetails.event,
    eventVersion: eventDetails.eventVersion,
    eventDateTime: this.getISOString(),
  };

  this._domainEvents.push(event);
}

🚀 Moving Forward

With the core Document type and its relationship to Entity established, some of the steps ahead include:

Develop the Agent entity: To fulfill the goals of this project, I want semi-to-full automation in the form of Agentic Orchestration. While I could simply develop agentic interactions as a service layer, I'd like to take it a step further and consider Agents as manageable business entities.

Review our Bounded Contexts: After our two primary entity sets are established, we'll review our decisions how they fit into the architectural strategies we've settled on, what complications there may be, and how to further set the structure of the solution going forward.

Implementing Repositories: Setting up data access layers to persist and retrieve entities.

🔍 It might seem like I’m overlooking “User” as an entity, but for now, I’m designing this system for a single user to simplify development and focus on core functionalities before expanding to a multi-user environment. While references to users owning documents or entities may appear, I’ll only revisit this concept later when preparing the UX, expanding to multi-user functionality, and needing to address authorization.

Closing Thoughts

Defining Document as an extension of Entity is more than a structural decision—it’s the cornerstone of a system that can grow as needed when more content types are required. This approach balances consistency, ease of expansion, and will be used similarly to have Agents and their component entities also extend Entity, making it a solid foundation for what’s to come.

What's Next

In the upcoming "Entities Part 2, Agents," I'll explore how Agents fit into this architecture, what sub entities may be needed based on the technology we'll be leveraging, and a few exciting concepts found in AWS Bedrock and Generally that'll inform those decisions.

Join the Conversation

I’m curious to know:

How do you prioritize which entities are essential when designing a system?
What role do you envision agents playing in business operations and creative projects?
Imagine a tool that could enrich content dynamically with the most relevant context—how would it fit into your workflow?

"Programs must be written for people to read, and only incidentally for machines to execute." -Harold Abelson and Gerald Jay Sussman

Helpful References

Clean Architecture by Robert C. Martin - A comprehensive guide on structuring systems for maintainability and scalability.
Domain-Driven Design: Tackling Complexity in the Heart of Software by Eric Evans - An in-depth look at managing complex software projects through domain modeling.
Implementing Domain-Driven Design by Vaughn Vernon - Practical examples and patterns for applying DDD principles.
The Serverless Advocate aka Lee Gilmore -Insights and best practices on serverless architectures and event-driven design, whose own examples are the basis of the base entity orchestration seen here.

My AI Adventure Begins

Michael Flanagan — Fri, 01 Nov 2024 14:45:35 +0000

🚀 Starting an AI Journey

AI is everywhere these days—🤖 LLMs, 🕵️‍♂️ agents, and beyond. I'm adding my own contribution to that 🌊 wave by starting this project blog. On the flip side, this project is an opportunity to embark on a learning journey—exploring how AI can help solve my personal challenges, from managing ✨ creative projects to organizing everyday 📋 information.

The biggest challenge is figuring out which problems in my life these solutions might address. To that end, I turned to my 🎨 hobbies and discovered a common theme across all of them—something that I could leverage the AI 💥 to help solve.

Whether it’s recording 📚 learnings from books and blogs, managing and sharing 🍲 recipes, or organizing 📖 narratives and notes for the tabletop games I run with friends, they all share a common need. Each requires a way to submit data with minimal structure, tag it contextually, and easily review, ✏️ edit, and aggregate that data.

This intersection of ⚙️ technology and everyday creativity is what excites me most. In the coming posts, I’ll explore how 🤖 LLMs and automated agents can help manage and elevate these processes, turning abstract capabilities into practical 🛠️ solutions.

⚔️ Challenges in Managing Creative Complexity

Running 🎲 tabletop games is a complex endeavor, especially when managing multiple games across different settings, each with its own set of evolving narratives, affected entities, and ongoing events. There are so many moving parts—characters with rich backstories, interlinked events, places with history—that the potential for losing or misplacing important details is high. Even with a solid ✍️ note-keeping system, it can feel overwhelming, and critical information can easily fall through the cracks.

This complexity, though challenging, is precisely what excites me and presents a significant opportunity for leveraging 🤖 AI. The more dynamic and intertwined these games get, the more potential there is for automated processes to streamline note-taking, identify 🔗 connections, and keep track of the myriad of details that otherwise could be lost or forgotten. Imagine having an 🤖 AI agent that not only keeps track of every NPC's motivations but also suggests new story twists based on past events. Each time I submit a new event, I get a glimpse into how it might affect planning and play workflows down the road.

While the primary focus is on narrative 🎲 tabletop games, the approach I'm building should be extensible to almost any agent-driven 🤖 LLM content management platform. Beyond games, I anticipate using this system for managing project and meeting notes, providing structure and context to different types of content, making the platform adaptable for broader use cases.

And, in a fun twist of going full 🔄 ouroboros, I’ll likely use this very platform to manage the project's own organization as it evolves.

🛠️ Making the Vision a Reality

The project has several key components that I'll dive into as we move forward. Each of these components plays a crucial role in building a system that can help manage creative and narrative-driven tasks effectively:

☁️ Serverless Architecture and AWS Services: Leveraging AWS for infrastructure and deployment is at the heart of this project. A "serverless first" approach means we can minimize maintenance, easily scale, and tap into the rich ecosystem that AWS offers. This provides the stable, reliable backbone needed for all other components to work effectively.

🤖 AI-Powered Agents: These agents are the core of the project. An AI agent, in this context, is a software program capable of interacting with its environment, collecting data, and using it to perform tasks aimed at achieving specific goals (AWS definition). While these agents hold great promise for managing complex tasks—such as tracking characters, plot twists, and evolving narratives—I remain skeptical about relying on them for key functions until their reliability is fully validated.

🐝 Agent Orchestration / Swarms: Beyond single agents, orchestration is a powerful concept. By coordinating multiple agents working towards a common goal, we can tackle larger, more dynamic problems in a distributed way. This approach is like having a "swarm" of helpers, each specializing in a different aspect of the narrative or data management, making the system more resilient and effective.

🛠️ Tool Use / Function Calling Framework: Agents should not just provide information; they need to act meaningfully within the system. This means being able to call external tools, invoke APIs, and interact with various parts of the platform to achieve their goals. This function-calling framework will enhance the practical utility of 🤖 AI agents by allowing them to be proactive contributors, not just passive assistants.

🏗️ Laying the Foundation

To get things moving, I'm starting by laying the groundwork—defining the entities and their basic actions. These entities will be the core building blocks, each with its own purpose and properties, and establishing those will give me a foundation to build on. The initial focus will also be on getting basic entity actions in place, creating the essential CRUD operations that will let me interact with and manipulate these entities in meaningful ways.

Initially, I'll be working with agents sequentially. This means one action at a time—no complex handoffs, no many-to-many agent relationships, and no intricate graph-like dependencies. I want to understand the flow deeply before trying to orchestrate more complex behaviors. There's something valuable about that simplicity: it forces you to consider every step, every action, and how one thing leads into the next.

It's worth mentioning that there are already frameworks designed to make this kind of orchestration much easier. Langchain and Langgraph come to mind, both of which are fantastic for streamlining agent interactions and orchestration. Recently, I also came across an educational framework from OpenAI around swarm orchestration that was a big inspiration for kicking off this project (OpenAI Swarm). But, to be honest, I want to be in the weeds. I want to feel the mistakes and learn from them firsthand. With 🤖 AI tooling becoming more commonplace, I think the "under the hood" knowledge might become harder to acquire if we always rely on ready-made solutions. So, I’m diving in headfirst, hoping that my path will be full of lessons—mistakes and all—that will make this journey interesting and engaging.

📅 What to Expect Moving Forward

In the upcoming posts, I'll dive deeper into specific components of the project, explore the challenges I encounter, and share the lessons I learn along the way. This series is going to be an evolving journey, and I’d love for you to follow along as things progress. Feel free to comment with your own experiences or share your thoughts on how these ideas might apply to your projects. I want to invite you to be part of this exploration—engage, provide feedback, and share your thoughts. Let's make this an engaging, shared experience!

"The world reveals itself to those who travel by foot" - Werner Herzog