Agent API design patterns in Agentic AI - ML Experiment: Train & Evaluate

Experiment - Agent API design patterns

Problem:You have built an AI agent that interacts with users and external tools via an API. The current API design is simple but causes issues with scalability, maintainability, and integration of new capabilities.

Current Metrics:API response time: 300ms average; Error rate: 5%; Developer onboarding time: 5 days

Issue:The API design is monolithic and tightly coupled, making it hard to add new features or fix bugs without affecting the whole system.

Your Task

Redesign the Agent API using modular design patterns to reduce error rate below 2%, improve response time to under 200ms, and reduce developer onboarding time to 2 days.

Keep backward compatibility with existing clients

Use only standard REST or GraphQL API styles

Do not change the underlying AI model

Hint 1

Hint 2

Hint 3

Hint 4

Solution

Agentic AI

from fastapi import FastAPI, APIRouter
from pydantic import BaseModel

app = FastAPI(title='Agent API with Modular Design')

# Define data models
class QueryRequest(BaseModel):
    query: str

class ToolRequest(BaseModel):
    tool_name: str
    parameters: dict

# Router for core agent functions
core_router = APIRouter(prefix='/core', tags=['core'])

@core_router.post('/query')
async def handle_query(request: QueryRequest):
    # Simulate processing query
    response = f"Processed query: {request.query}"
    return {"response": response}

# Router for tool integrations
tools_router = APIRouter(prefix='/tools', tags=['tools'])

@tools_router.post('/execute')
async def execute_tool(request: ToolRequest):
    # Simulate tool execution
    result = f"Executed {request.tool_name} with {request.parameters}"
    return {"result": result}

# Versioning router
v1_router = APIRouter(prefix='/v1')
v1_router.include_router(core_router)
v1_router.include_router(tools_router)

app.include_router(v1_router)

# Facade endpoint to simplify client interaction
@app.post('/agent/query')
async def agent_query(request: QueryRequest):
    # Internally call core query handler
    return await handle_query(request)

@app.post('/agent/tool')
async def agent_tool(request: ToolRequest):
    # Internally call tool execution handler
    return await execute_tool(request)

# Run with: uvicorn filename:app --reload

Split API into modular routers for core and tools functionality

Added versioning prefix to support backward compatibility

Implemented Facade endpoints to simplify client calls

Used FastAPI for asynchronous, fast response handling

Separated concerns to improve maintainability and onboarding

Results Interpretation

Before: Response time 300ms, Error rate 5%, Onboarding 5 days

After: Response time 180ms, Error rate 1.5%, Onboarding 2 days

Using modular API design patterns like Facade, Adapter, and versioning reduces complexity, improves performance, and makes the system easier to maintain and extend.

Bonus Experiment

Try implementing a GraphQL API version of the agent that allows clients to request exactly the data they need.

💡 Hint

Use a GraphQL library compatible with your framework and define schemas that map to your agent's capabilities.

Practice

1. What is the main purpose of using Agent API design patterns in AI systems?

easy

A. To organize how AI agents communicate and work together

B. To speed up the training of machine learning models

C. To store large datasets efficiently

D. To improve the hardware performance of AI servers

Solution

1. Step 1: Understand the role of Agent API design patterns

   These patterns help define clear communication and interaction rules between AI agents.

2. Step 2: Compare with other options

   Options A, C, and D relate to training speed, data storage, and hardware, which are not the focus of Agent API design patterns.

3. Final Answer:

   To organize how AI agents communicate and work together -> Option A

4. Quick Check:

   Agent API design patterns = organize communication [OK]

Hint: Agent API patterns focus on agent communication, not hardware or data [OK]

Common Mistakes:

• Confusing design patterns with hardware optimization
• Thinking patterns speed up model training directly
• Mixing data storage with agent communication

2. Which of the following is the correct way to define a simple message passing function in an Agent API?

easy

A. def send_message(agent, message): return message + agent

B. def send_message(agent, message): agent.send(message)

C. def send_message(agent, message): return agent.receive(message)

D. def send_message(agent, message): print(agent + message)

Solution

1. Step 1: Analyze the function purpose

   The function should send a message to an agent and get a response by calling the agent's receive method.

2. Step 2: Check each option

   def send_message(agent, message): return agent.receive(message) correctly calls agent.receive(message). def send_message(agent, message): agent.send(message) calls agent.send which is not standard. Options A and C incorrectly try to add or print agent and message.

3. Final Answer:

   def send_message(agent, message): return agent.receive(message) -> Option C

4. Quick Check:

   Message passing calls agent.receive(message) [OK]

Hint: Message passing calls agent.receive(message) to send data [OK]

Common Mistakes:

• Using agent.send instead of agent.receive
• Trying to concatenate agent object with string
• Printing instead of returning the message

3. Given the code below, what will be the output?

class Agent:
    def receive(self, message):
        return f"Received: {message}"

def send_message(agent, message):
    return agent.receive(message)

agent = Agent()
print(send_message(agent, "Hello"))

medium

A. Error: method not found

B. Hello

C. send_message(agent, Hello)

D. Received: Hello

Solution

1. Step 1: Understand the Agent class and receive method

   The receive method returns the string 'Received: ' plus the message passed.

2. Step 2: Trace the send_message call

   send_message calls agent.receive with "Hello", so it returns 'Received: Hello'.

3. Final Answer:

   Received: Hello -> Option D

4. Quick Check:

   agent.receive("Hello") = "Received: Hello" [OK]

Hint: Agent.receive returns 'Received: ' plus message [OK]

Common Mistakes:

• Expecting just the message without prefix
• Thinking send_message prints instead of returns
• Assuming method does not exist causing error

4. Identify the error in the following Agent API code snippet:

class Agent:
    def receive(self, message):
        print(f"Got message: {message}")

def send_message(agent, message):
    return agent.receive(message)

agent = Agent()
response = send_message(agent, "Hi")
print(response)

medium

A. The receive method should return a value, not just print

B. send_message should not call agent.receive

C. Agent class is missing an __init__ method

D. The print statement in send_message is incorrect

Solution

1. Step 1: Check receive method behavior

   receive only prints the message but does not return anything, so it returns None by default.

2. Step 2: Analyze send_message and print(response)

   send_message returns None, so printing response outputs None, which is likely unintended.

3. Final Answer:

   The receive method should return a value, not just print -> Option A

4. Quick Check:

   receive must return message for send_message to work [OK]

Hint: receive must return, not just print, to pass data back [OK]

Common Mistakes:

• Ignoring that print returns None
• Thinking __init__ is required here
• Confusing print location with syntax error

5. You want to design an Agent API where multiple agents can collaborate by passing messages and roles define their behavior. Which design pattern best supports this?

hard

A. Factory pattern to create agents dynamically

B. Mediator pattern to centralize communication between agents

C. Singleton pattern to ensure one agent instance

D. Observer pattern to notify agents of state changes

Solution

1. Step 1: Understand collaboration and role-based behavior

   Agents need a central way to communicate and coordinate roles effectively.

2. Step 2: Match design patterns to needs

   The Mediator pattern centralizes communication, making it ideal for agent collaboration. Singleton limits to one instance, Factory creates objects, Observer handles notifications but not central communication.

3. Final Answer:

   Mediator pattern to centralize communication between agents -> Option B

4. Quick Check:

   Collaboration with roles = Mediator pattern [OK]

Hint: Mediator centralizes agent communication for collaboration [OK]

Common Mistakes:

• Choosing Singleton which limits to one agent
• Confusing Factory with communication pattern
• Using Observer which is for event notification only