Agent Development

Design and build effective AI agents with appropriate architectures, memory configurations, model selection, and tool setups. Works across any agent framework or custom implementation.

When to Use

• Starting a new agent project
• Choosing between agent architectures (single-agent, multi-agent, stateless, stateful)
• Designing memory structure and context management
• Selecting appropriate models for your use case
• Planning tool configurations
• Optimizing memory management and performance
• Implementing shared memory between agents
• Debugging memory-related issues

Architecture Selection

Read resources/architectures.md for detailed comparison and tradeoffs.

Memory Architecture

Three memory types cover most agent needs:

Core Memory (in-context):

• Always accessible in the agent's context window
• Use for: current state, active context, frequently referenced information
• Limit: Keep total core memory under 80% of context window

Archival Memory (out-of-context):

• Semantic search over vector database or document store
• Use for: historical records, large knowledge bases, past interactions
• Access: Agent must explicitly search — not automatically populated from context overflow

Conversation History:

• Past messages from current conversation
• Use for: referencing earlier discussion, tracking conversation flow
• Older messages may be evicted; store durable facts in core/archival memory

Read resources/memory-architecture.md for detailed guidance.

Memory Block Design

Core principle: One block per distinct functional unit.

Essential blocks:

• persona: Agent identity, behavioral guidelines, capabilities
• human: User information, preferences, context

Add domain-specific blocks based on use case:

• Customer support: company_policies, product_knowledge, customer
• Coding assistant: project_context, coding_standards, current_task
• Personal assistant: schedule, preferences, contacts

Guidelines:

• Keep blocks focused and purpose-specific
• Use clear, instructional descriptions
• Monitor size limits (typically 2000-5000 characters per block)
• Design for append operations when sharing memory between agents

Read resources/memory-patterns.md for domain examples and resources/description-patterns.md for writing effective descriptions.

Model Selection

Avoid for production agents:

• Models without reliable function/tool calling support
• Small local models (<7B parameters) for tool-use-heavy agents

Read resources/model-recommendations.md for detailed guidance.

Tool Configuration

Start minimal: Attach only tools the agent will actively use.

Common starting points:

• Memory tools (insert, replace, search): Core for most stateful agents
• File system tools: When the agent needs to read/write files
• Custom tools: For domain-specific operations (databases, APIs, etc.)

Tool rules: Enforce sequencing when needed (e.g., "always call search before answer").

Read resources/tool-patterns.md for common configurations.

Advanced Topics

Memory Size Management

When approaching character limits:

1. Split by topic: customer_profile → customer_business, customer_preferences
2. Split by time: interaction_history → recent_interactions, archive older to archival memory
3. Archive historical data: Move old information to archival memory
4. Consolidate: Summarize and rewrite block

Read resources/size-management.md for strategies.

Concurrency Patterns

When multiple agents share memory or an agent processes concurrent requests:

Safest operations:

• Append-only writes (minimal race conditions)
• Database-backed storage with row-level locking

Risk of race conditions:

• Replace operations: target string may change before write
• Full rewrites: last-writer-wins, no merge

Best practices:

• Design for append operations when possible
• Reserve full rewrites for single-agent exclusive access

Read resources/concurrency.md for detailed patterns.

Implementation Examples

Python (SDK-based)

agent = client.agents.create(
    name="my-agent",
    model="gpt-4o",
    memory_blocks=[
        {"label": "persona", "value": "You are a helpful assistant..."},
        {"label": "human", "value": "User preferences and context..."},
        {"label": "project", "value": "Current project details..."},
    ],
)

TypeScript (SDK-based)

const agent = await client.agents.create({
  name: "my-agent",
  model: "gpt-4o",
  memoryBlocks: [
    { label: "persona", value: "You are a helpful assistant..." },
    { label: "human", value: "User preferences and context..." },
    { label: "project", value: "Current project details..." },
  ],
});

CLI-based

Most agent frameworks provide a CLI for interactive agent creation and configuration. Check your framework's documentation for creating new agents, setting names and descriptions, configuring memory blocks, and attaching tools.

Validation Checklist

Architecture:

• Does the architecture match the model's capabilities?
• Is the model appropriate for expected workload and latency?

Memory:

• Is core memory total under 80% of context window?
• Is each block focused on one functional area?
• Are descriptions clear about when to read/write?
• Have you planned for size growth and overflow?
• If multi-agent, are concurrency patterns considered?

Tools:

• Are tools necessary and properly configured?
• Are memory blocks granular enough for effective updates?

Common Antipatterns

Too few memory blocks: Everything in one block makes updates expensive and imprecise. Split into focused blocks.

Too many memory blocks: 10+ blocks when 3-4 would suffice. Start minimal, expand as needed.

Poor descriptions: data: "Contains data" tells the agent nothing. Provide actionable guidance about when to read/write.

Ignoring size limits: Blocks grow indefinitely until they hit limits. Monitor and manage proactively.

Resources

• resources/architectures.md — Architecture comparison and selection
• resources/memory-architecture.md — Memory types and when to use them
• resources/memory-patterns.md — Domain-specific memory block examples
• resources/description-patterns.md — Writing effective block descriptions
• resources/size-management.md — Managing memory block size limits
• resources/concurrency.md — Multi-agent memory sharing patterns
• resources/model-recommendations.md — Model selection guidance
• resources/tool-patterns.md — Common tool configurations