Five agents walk into a production environment. Four of them crash. Here’s why—and how to build the one that doesn’t.

You know how AgentShip works under the hood. You’ve seen the architecture, understood the tradeoffs, and maybe even spun up your first agent. But here’s the thing: knowing the tools doesn’t mean knowing the patterns.

I’ve spent the last two years building production AI agents from health assistant to internal tooling at Audible. I’ve shipped agents that worked, and watched agents that crashed spectacularly. Through all of it, I’ve learned that most agent systems fall into five core patterns.

Get the pattern right, and your agent just works. Get it wrong, and you’ll spend weeks debugging why GPT-4 “forgot” the conversation or why your tool calls are timing out.

Let me save you those weeks.

The Five Patterns

Here’s the reality: 90% of production agents follow one of these five patterns. Master them, and you can build almost anything.

┌─────────────────────────────────────────┐
│ 1. Single-Shot        │ Fast, stateless │
│ 2. Conversational     │ Multi-turn chat │
│ 3. Tool-Calling       │ External actions│
│ 4. Multi-Agent        │ Orchestration   │
│ 5. Human-in-the-Loop  │ Approval gates  │
└─────────────────────────────────────────┘

Let’s break down each one with real code and real lessons.

Pattern 1: Single-Shot Agent

The simplest agent that could possibly work.

Single-shot agents do one thing: take an input, process it, return an output. No memory, no conversation history, no state. Think of them as fancy functions.

When to Use It

• Summarizing documents

• Classifying text (spam detection, sentiment analysis)

• Data extraction (parse PDFs, scrape structured data)

• Batch processing thousands of items

Real Example: Customer Support Ticket Summarizer

After a customer support conversation, we need to summarize what happened. The agent doesn’t need to remember previous summaries - each one is independent.

AgentShip Configuration

agent_name: ticket_summarizer
tags: [support, summarization]
llm_provider_name: openai
llm_model: gpt-4o
temperature: 0.3
execution_engine: adk
streaming_mode: event_based

description: Summarizes customer support conversations

instruction_template: |
  You are a customer support summarization expert.
  
  Summarize the customer conversation in 3 bullet points:
  - Customer issue/question
  - Actions taken
  - Resolution status
  
  Input format:
  - conversation: The full conversation transcript
  
  Output: A concise summary with 3 bullet points

tools: []  # No external tools needed

Why it works:

• Fast: No session lookup overhead

• Scalable: Stateless means easy horizontal scaling

• Simple: Fewer things to break

Production lesson: We process 10,000+ summaries per day. Single-shot agents scale beautifully because there’s no shared state to coordinate.

Pattern 2: Conversational Agent

The pattern that made chatbots possible.

Conversational agents maintain context across multiple turns. They remember what you said three messages ago and can reference it. This is where sessions become critical.

When to Use It

• Chat interfaces (customer support, personal assistants)

• Progressive disclosure (asking clarifying questions)

• Contextual recommendations

• Any multi-turn interaction

Real Example: E-commerce Shopping Assistant

A user might say: “I’m looking for a laptop.” The agent asks follow-up questions about budget, use case, and preferences, remembers the answers, and provides personalized recommendations based on the full conversation.

AgentShip Configuration

agent_name: shopping_assistant
tags: [ecommerce, shopping, conversational]
llm_provider_name: openai
llm_model: gpt-4o
temperature: 0.7
execution_engine: adk
streaming_mode: event_based

# Enable session management for conversation history
session_enabled: true
session_memory_window: 20  # Keep last 20 messages

description: Personal shopping advisor with conversation memory

instruction_template: |
  You are a friendly shopping assistant helping users find products.
  
  You can:
  - Ask clarifying questions about budget, preferences, use case
  - Remember previous messages in the conversation
  - Provide personalized product recommendations
  
  Be conversational and helpful. Build on what the user has already told you.
  
  Input format:
  - message: User's current message
  - conversation_history: Automatically provided by AgentShip

tools: []  # Could add product search tools here

Why it works:

• Context window management: Keep the last N messages

• Session isolation: Each user has their own history

• Natural conversation: Feels like talking to a human

Production lesson: We learned the hard way that you need to truncate old messages. Our first version tried to load the entire conversation history, it broke when users had 100+ messages. Now we keep the last 20 messages plus a rolling summary of older ones.

Pattern 3: Tool-Calling Agent

When your agent needs to do more than talk.

Tool-calling agents can interact with the outside world: query databases, call APIs, fetch real-time data. This is where agents become truly useful.

When to Use It

• Database lookups (find customer orders, check inventory)

• API integrations (weather, stock prices, booking systems)

• File operations (read, write, search documents)

• Any action that requires external data

Real Example: Product Search Agent

When a user is looking for products, the agent searches the product database and returns matches based on category, price range, and specifications.

AgentShip Configuration

agent_name: product_search
tags: [ecommerce, search, tools]
llm_provider_name: openai
llm_model: gpt-4o
temperature: 0.3
execution_engine: adk
streaming_mode: event_based
max_tool_iterations: 5  # Prevent infinite loops

description: Finds products matching user criteria using database tools

instruction_template: |
  You are a product search expert. Use the available tools to find products.
  
  Available tools:
  - search_products: Search by category, price, keywords
  - get_inventory: Check stock availability for a product
  
  Always use tools to get real data. Do not make up product information.
  
  Input format:
  - query: User's product search request
  
  Output: Product recommendations with prices and availability

tools:
  - type: function
    id: search_products
    function_name: search_products_db
    function_class: src.tools.product_tools.ProductSearchTool
    description: Search for products by category, price, and specs
    parameters:
      category:
        type: string
        description: Product category
      max_price:
        type: number
        description: Maximum price filter
      keywords:
        type: string
        description: Search keywords
  
  - type: function
    id: get_inventory
    function_name: get_product_inventory
    function_class: src.tools.product_tools.InventoryTool
    description: Check product availability and stock
    parameters:
      product_id:
        type: string
        description: Product identifier

Why it works:

• Function calling: Modern LLMs know how to use tools

• Structured output: Tools return JSON, not prose

• Error handling: If a tool fails, the agent can try another approach

Production lesson: Always set max_iterations. We had an agent that got stuck in a loop calling the same tool 47 times before we killed it. Now we limit to 5 iterations and return a helpful error message if we hit the limit.

Pattern 4: Multi-Agent Orchestration

When one agent isn’t enough.

Multi-agent systems split complex tasks across specialized agents. Each agent is an expert in one domain, and an orchestrator coordinates them.

When to Use It

• Complex workflows (process documents → extract data → validate → store)

• Specialized domains (one agent for legal, one for finance, one for medical)

• Parallel processing (summarize 10 documents simultaneously)

• Divide and conquer strategies

Real Example: Invoice Processing Pipeline

When a user uploads an invoice, we need to:

1. Extract text from the PDF

2. Identify the invoice type and vendor

3. Parse line items and amounts

4. Validate against purchase orders

5. Generate a summary for approval

No single agent does all of this well. So we built five specialized agents.

AgentShip Configuration

agent_name: invoice_processor
tags: [finance, invoice, orchestrator]
llm_provider_name: openai
llm_model: gpt-4o
temperature: 0.2
execution_engine: adk
streaming_mode: event_based

description: Orchestrates invoice processing through specialized sub-agents

instruction_template: |
  You are an invoice processing orchestrator.
  
  Process invoices using these specialized agents in order:
  1. TextExtractor - Extract text from PDF
  2. InvoiceClassifier - Identify invoice type and vendor
  3. LineItemParser - Parse amounts and line items
  4. POValidator - Validate against purchase orders
  5. InvoiceSummarizer - Generate approval summary
  
  Pass outputs from each agent to the next in the pipeline.
  
  Input format:
  - pdf_url: URL to the invoice PDF
  
  Output format (JSON):
  - text: Extracted text
  - invoice_type: Classification result
  - line_items: Parsed items
  - validation: PO validation results
  - summary: Human-readable summary

tools:
  # Order matters: agents are called sequentially
  - type: agent
    id: text_extractor
    agent_class: src.agents.invoice.TextExtractorAgent
  
  - type: agent
    id: invoice_classifier
    agent_class: src.agents.invoice.InvoiceClassifierAgent
  
  - type: agent
    id: line_item_parser
    agent_class: src.agents.invoice.LineItemParserAgent
  
  - type: agent
    id: po_validator
    agent_class: src.agents.invoice.POValidatorAgent
  
  - type: agent
    id: invoice_summarizer
    agent_class: src.agents.invoice.InvoiceSummarizerAgent

Why it works:

• Specialization: Each agent is optimized for one task

• Modularity: Swap out agents without rewriting the pipeline

• Debugging: Easy to isolate which step is failing

Production lesson: Multi-agent systems add latency. Our pipeline takes 8-12 seconds to run all five agents sequentially. We optimized by running steps in parallel where possible (e.g., classification and value extraction can happen simultaneously). This cut our latency in half.

Pattern 5: Human-in-the-Loop Agent

For when the stakes are too high to trust AI alone.

Human-in-the-loop agents pause at critical decision points and wait for human approval before proceeding. This is essential for high-stakes operations.

When to Use It

• Financial transactions (approve payments, transfers)

• Legal/compliance decisions (approve filings, sign documents)

• Medical actions (prescribe medication, schedule procedures)

• Learning mode (verify agent behavior before full automation)

Real Example: Payment Processing Agent

When the agent suggests making a payment or transfer, we don’t do it automatically. We ask the user to confirm first.

agent_name: payment_processor
tags: [finance, payment, approval]
llm_provider_name: openai
llm_model: gpt-4o
temperature: 0.1  # Very deterministic for financial operations
execution_engine: adk
streaming_mode: event_based

# Human-in-the-loop configuration
approval_required: true
approval_timeout: 300  # 5 minutes
approval_actions:
  - send_payment
  - transfer_funds
  - process_refund

description: Processes payments with human approval gates

instruction_template: |
  You are a payment processing agent with strict approval requirements.
  
  For HIGH-STAKES actions (payments, transfers, refunds):
  1. Parse the user's intent
  2. Validate the payment details
  3. Request human approval (automatic gate)
  4. Execute ONLY if approved
  
  For LOW-STAKES actions (check balance, view history):
  - Execute immediately, no approval needed
  
  Input format:
  - message: User's payment request
  
  Output format:
  - For approved payments: Confirmation with transaction ID
  - For denied payments: Acknowledgment without action

tools:
  - type: function
    id: process_payment
    function_name: send_payment
    function_class: src.tools.payment_tools.PaymentTool
    requires_approval: true  # Triggers human approval
    description: Send a payment (requires approval)
    parameters:
      recipient:
        type: string
        description: Payment recipient
      amount:
        type: number
        description: Payment amount
      currency:
        type: string
        description: Currency code (USD, EUR, etc.)
  
  - type: function
    id: check_balance
    function_name: get_balance
    function_class: src.tools.payment_tools.BalanceTool
    requires_approval: false  # No approval needed
    description: Check account balance
    parameters: {}

Implementation details:

• Approval UI: AgentShip provides a simple approval widget

• State management: The agent’s state is persisted while waiting

• Timeout handling: If the user doesn’t respond in 5 minutes, we cancel

• Audit trail: Every approval/denial is logged

Production lesson: Users hate waiting. We originally had a 30-second timeout, which was too short—users would miss the notification. We increased it to 5 minutes, but also added the ability for agents to suggest actions without blocking, so users can approve asynchronously.

Subscribe now

Putting It All Together ?

Rule of thumb: Start simple. Most teams over-engineer their first agent. Begin with a single-shot or conversational agent, then add complexity only when needed.

What’s Next?

You now know the five patterns that cover 90% of production agent systems. But there’s a missing piece: memory.

Sessions give you short-term memory (the last 20 messages). But what about long-term memory? How do you let your agent remember things from weeks ago without loading every message into the context window?

That’s where semantic memory, vector databases, and retrieval strategies come in.

In the next article, we’ll dive into Memory with AgentShip: short-term vs long-term memory, semantic search, pgvector integration, and the memory patterns that make agents actually intelligent.

Subscribe now

Remember the 2-3 week sprints of effort where you tried to get an agent into production? Endless configuration files, the sessions management headaches, the “we’ll add observability later” promises that never get delivered ?

Here’s what 30 minutes should look like instead.

I’m going to build a conversational AI agent, add observability, and deploy it to production. In real-time. With actual commands, real outputs, and yes, even an error or two (because that’s how real development works).

Grab your Morning Herbal Tea (I am a herbal tea person !) and let's ship an agent.

What We’re Building

Goal: A production-ready conversational agent with:

• Google ADK for orchestration

• GPT model for conversation

• Session management using Postgres that actually works

• A Debug UI that helps you debug

• Opik observability out of the box

• A real API endpoint you can hit

The twist? We’re not writing session logic, API routes, or observability wrappers. AgentShip handles all of that.

The Workspace Setup (One time)

Although it could take 5 mins to 10 mins to setup your workspace initially, but this effort will be one time and will help you in long run.

Clone and Enter

$ git clone https://github.com/Agent-Shipping-Kit/agent-ship.git
$ cd agent-ship

Environment Setup :

Create your .env file:

Pro tip: AgentShip uses a .env.example template, just copy and fill:

$ cp .env.example .env

Fill out necessary environment variables and ignore others. Codebase handles that.

OPENAI_API_KEY=your_openai_api_key_here

Setting up Opik account:

Setup your opik environment variables by creating your opik account here. Create a workspace and a project under the workspace. Once

Setting up Opik Environment Variables in .env

OPIK_API_KEY=your-api-key
OPIK_WORKSPACE='the-engineers-digest-agent-ship' #create as you like
OPIK_PROJECT_NAME='project1'

Makefiles and Docker setup

Once the environment variables are setup, we need to install the crucial dependencies, the postgres based session store, spinning up the API server, debug ui etc. etc…

Too much right ! Hence we have docker files setup to make it easy. Sometimes it is hard to remember docker commands for developers and I believe it is a waste of time to look into the commands, hence we created Makefiles that makes it a one command spin up.

$ make docker-setup

Tadaah! you are done and you can now access out of box agents available in the repository! 👏

The Old Way vs. The AgentShip Way

Create Your Agent - 10 mins

Now, Once the base setup is done, we need to create an agent. For this demo we will keep it simple and create a simple agent that spits out the history facts on innovations based on year provided in the natural language.

Note: We will cover the more advanced design patterns in coming weeks !

Setting up the agent requires setting up the yaml configuration which is present in main.yaml and the actual agent logic main.py in all_agents location.

Run the following commands:

$ mkdir src/agents/all_agents/my_new_demo_agent
$ cd src/agents/all_agents/my_new_demo_agent
$ touch src/agents/all_agents/my_new_demo_agent/__init__.py
$ touch src/agents/all_agents/my_new_demo_agent/main_agent.py
$ touch src/agents/all_agents/my_new_demo_agent/main_agent.yaml

We will spend around 10 mins in this section, this this is the most complicated and important of all the process.

Agent Configuration in YAML

Simple yaml that defines the prompt to be used by agent. We are aiming for structured inputs and outputs and confining the scope to history facts for the agent.

agent_name: history_facts_agent
tags: [history_facts_agent]
llm_provider_name: openai
llm_model: gpt-4o
temperature: 0.4
description: Agent that helps answering question about history facts. 
instruction_template: >
  You are a history expert. You are able to spit facts about history and answer questions about it.
  history facts are based on the year provided by the user. If not provided, you can ask the user to provide the year.
  
  CRITERIA FOR GETTING HISTORY FACTS:
  - If the user provides a year, you should get the history facts for that year.
  - If the user does not provide a year, you should ask the user to provide the year.

  GUARDRAILS:
  - You should not provide any information that is not related to the history facts.
  
  You will receive input in the following format:
  HistoryFactsInput model:
  - query: The query to get the history facts for.

  Your output should be a JSON object matching the HistoryFactsOutput model. Please make sure to include all the fields in the output and output should be a JSON object.

  HistoryFactsOutput model:
  - facts: List[str]

Agent Logic

Defining the agent logic involves setting up the structured input, output and the initialization. Most of complexity is taken care by AgentShip ! Simple enough right ! 🚀

"""History facts agent using Google ADK for history facts generation."""

from typing import List
from pydantic import BaseModel, Field
from src.agents.all_agents.base_agent import BaseAgent


class HistoryFactsInput(BaseModel):
    """Input for history facts generation."""
    query: str = Field(description="The query to get the history facts for.")


class HistoryFactsOutput(BaseModel):
    """Output for history facts generation."""
    facts: List[str] = Field(description="The history facts for the query.")


class HistoryFactsAgent(BaseAgent):
    """Agent for generating history facts."""

    def __init__(self):
        """Initialize the history facts agent."""
        # Config auto-loads from main_agent.yaml, chat() is implemented by base class
        super().__init__(
            _caller_file=__file__,
            input_schema=HistoryFactsInput,
            output_schema=HistoryFactsOutput
        )
    
    # No need to override chat() - base class handles it!
    # No need to override _create_tools() or _create_sub_agents() - defaults to empty list

That is it! Let us restart the docker 🐳 !

$ make docker-restart

or

$ make docker-reload

Debugging with Debug UI - 5-10 mins

Once the docker is restarted, you need to head to debug-ui to interact with your agent and check its behavior and performance.

Note: We did not add any advanced guardrails here for simplicity but we will covering that in coming weeks!

Now, head over to http://localhost:7001/debug-ui

You should see the UI like below, where you can now chat with the agent.

Did you notice something ? Agent has the past chat context 😀 thought we did not do any setup around it by ourselves.

Clap 👏 for yourself because you have just setup an agent in a very minimalistic way with which you can interact and debug easily.

Feel free to make any changes to make it work as per your needs. For now we will move towards observability and shipping to production.

Observability with Opik - 5-10 mins

We are using Opik under the hood for observability on the agents. You do not need to do anything special here as you already have setup the .env with opik environment variables by now.

So just head onto your opik account and check your agent logs. You should see something like this. Good enough right without much of efforts !

I would encourage you to play around the Opik UI more to understand it better. There is a good documentation out there to refer to.

Shipping an API endpoint - 2 mins

Well now that you have your agent ready and tuned for performance based on observability, you would want to access the Agent. Access via other services like the backend service for your frontend. For that this Agent needs to be deployed as an API with right authentication practices.

Don’t worry ! AgentShip takes care of setting up api endpoint for you with authentication.

As of today we are support heroku for deployment and will add support for cloud based deployments soon like Azure, AWS and GCP. For the scope of this article we will focus on Heroku deployment.

$ make heroku-deploy

You need up the APP_NAME and SESSION_STORE_NAME for your heroku app in .env file

APP_NAME='the-agent-ship-demo'
SESSION_STORE_NAME='agent-ship-demo-session-store'

You might get output like

That’s all! you API is deployed ! Don’t worry, I have deleted my heroku container after this demo! So don’t bother to hack! 😊

Note: When it comes to scalability we need more advanced configurations. we will cover those configurations in detail in a separate post.

Verifying the API - 2 mins

Once deployment is done, you might be treated with this message when you open the url

You can call this API using Postman for which the configurations and all are in the repo.

Conclusion

That’s it! In 30 minutes, you’ve built and deployed a API-ready AI agent with observability, session management, and authentication - all baked in.

No more week-long sprints. This is what modern agent development should look like.

Checkout the Github repo here: https://github.com/Agent-Shipping-Kit/agent-ship

Next week:

We will share how to implement Advanced Agentic Design Patterns - multi-agent orchestration, tool integration patterns with AgentShip.

Stay tuned, and happy shipping! 🚀

I spent two days building an agent last month. It worked perfectly. Answered questions, called the right tools, handled edge cases. I was proud of it.

Then I tried to ship it. Two weeks later, after writing FastAPI endpoints, setting up PostgreSQL sessions, wiring Opik for observability, writing Docker configs, and debugging why the health check kept timing out in production, the agent still did the exact same thing it did on day two.

I’d just spent 12 days wrapping it in plumbing. This happened three times. By the third agent, while copy-pasting my session manager code again, I realized: I’m rebuilding the same thing every time. So I stopped and I built it once.

What shipping an agent actually looks like

Let me show you the breakdown from my last agent before I had any framework:

Day 1-2: Build the agent

The fun part. Write the logic, test it in Jupyter, get it working. Agent does what I want.

Day 3-5: Wrap it in FastAPI

Request validation, error handling, CORS headers, environment variables. Tedious but straightforward. Copy-paste from last project, tweak, move on.

Day 6-7: Add sessions

Users expect conversations, not isolated requests. PostgreSQL or Redis? I pick PostgreSQL. Write the schema, write the session manager, handle concurrent requests, add cleanup logic.

Day 8-9: Wire up observability

Need to know what’s happening in production. Token counts, latency, tool traces, error logs. Integrate Opik, wrap every agent call in tracing decorators.

Day 10-12: Deploy it

Write Dockerfile, docker-compose, realize I forgot the health check endpoint, fix database migration order, deploy to Heroku, crash because connection pool limit not set.

Day 13-14: Debug production

Works locally. Slow in production. Database in wrong region. Move it. Still crashes occasionally. Not closing connections properly. Fix. Finally works.

Two weeks. The agent does the exact same thing it did on day two !!

How AgentShip works

AgentShip sits between your agent and production. You write two files (YAML config + Python class), and it handles the API server, session management, Memory, Tools, MCP, observability, and deployment for you.

Note: For the full architecture and what’s happening under the hood feel free to check out Github repository. Feel free to provide stars and forks for the repository. We really appreciate it!

What we Write

Agent configuration

# agent_config.yaml
agent_name: my_agent
llm_model: gpt-4
temperature: 0.7
  You are a helpful assistant that...

Agent Logic

# [agent.py](http://agent.py)
from agentship import BaseAgent

class MyAgent(BaseAgent):
    def __init__(self):
        super().__init__(__file__)

What we get:

make docker-setup → local dev with API + sessions + observability

make heroku-deploy → production deployment

Real Numbers From Experimentation

We’re using AgentShip in experimentation for a consumer app that’s currently in the build phase.

1. Conversation summarizer → Takes user transcripts, extracts key points

2. Q&A assistant → Answers questions using conversation history + knowledge base

3. Action item extractor → Pulls follow-ups and next steps

4. Document analyzer → Processes documents, summarizes findings

Deployed the whole stack in a weekend. As we iterate on the product, we’re spending time improving agent quality and user experience instead of debugging infrastructure.

Try it

Here’s the quick start:

git clone [https://github.com/Agent-Shipping-Kit/agent-ship.git]
cd agent-ship

make docker-setup

# Create your agent (2 files)
# Check the examples/ folder
# Check the docs
# Use the Debug-UI for testing

make heroku-deploy (More deployment options coming)

You’ll have a production API in 30 minutes.

The code is on GitHub. It’s free and open source. If you find bugs, open an issue. If you want features, open the feature requests or submit a PR.

GitHub: https://github.com/Agent-Shipping-Kit/agent-ship.git

If you appreciate the work, feel free to star the repository, that works as the encouragement for us to improvise and deliver.

Next week:

We will share a demo on how to create a agent, test it, deploy it in production. Stay tuned.