AI Agents
Build autonomous AI agents that can use tools, make decisions, and complete complex tasks.
Experimental Feature
AI Agents are currently optimized for single-turn tasks and straightforward tool calling. Multi-turn conversations may have limitations while we enhance reasoning capabilities.
What are AI Agents?
Agents are LLMs that can interact with external systems through tools. Unlike chatbots that only answer questions, agents can:
- Take Actions - Call APIs, send emails, update databases
- Gather Information - Look up data from multiple sources
- Make Decisions - Choose which tools to use and when
- Complete Tasks - Handle multi-step workflows autonomously
How Agents Work: ReAct Loop
Agents use the ReAct (Reasoning + Acting) pattern:
- Think - Analyze the user's request
- Act - Choose and execute a tool
- Observe - Process tool output
- Repeat - Continue until task is complete
- Respond - Return final answer
Example execution:
User: "What's the weather in NYC and should I bring an umbrella?"
Step 1 (Think): I need to check the current weather
Step 2 (Act): Call get_weather(city="New York")
Step 3 (Observe): Temperature: 72°F, Conditions: Partly cloudy, Rain: 20%
Step 4 (Think): 20% rain is low, umbrella probably not needed
Step 5 (Respond): "It's 72°F and partly cloudy with only 20% chance
of rain. An umbrella probably isn't necessary."
Use Cases
- Customer Support - Look up orders, process returns, answer FAQs
- Data Analysis - Query databases, generate reports, spot trends
- Automation - Schedule tasks, send notifications, update records
- Research - Gather information from multiple sources, summarize findings
Creating Agents
Step 1: Define Your Agent
- Go to My Agents
- Click Create Agent
- Fill in basic info:
- Name -
customer-support-agent
- Description - What your agent does
- System Prompt - Instructions for the agent
Example system prompt:
You are a helpful customer support agent. Use the available tools
to look up customer information and order details. Be polite and
professional. If you find an issue, offer to help resolve it.
When the user asks about an order, use the order_lookup tool with
their order ID. Always confirm the customer's information before
taking any action.
Step 2: Choose Base Model
Select the LLM that powers your agent:
- Base Model - Use a supported model directly (Llama 3.1/3.3)
- Adapter - Use your fine-tuned LoRA adapter
Tools give your agent capabilities to interact with external systems.
Tools must be created first in My Tools, then you can select them when creating or editing your agent.
For complete details on creating and configuring tools, see Tools Documentation.
Quick summary:
- Each tool is an HTTP endpoint (GET, POST, etc.)
- Define name, description, parameters, and authentication
- Select tools when creating your agent
Define structured output format:
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": ["order_lookup", "customer_info", "final_answer"]
},
"order_id": {"type": "string"},
"answer": {"type": "string"}
}
}
If not specified, schema is auto-generated from your tools.
Step 5: Set Parameters
- Max Iterations - Maximum tool calls (default: 5)
- Temperature - Creativity (0 = deterministic, 1 = creative)
Step 6: Test & Deploy
Click Create - your agent is live immediately!
Testing in Playground
Test agents interactively before deploying:
- Go to your agent → click Playground button
- Enter a test query
- Watch the agent work step-by-step:
Step 1: LLM Call
Agent thinks: "I need to look up order #12345"
Response: {"action": "order_lookup", "order_id": "12345"}
Step 2: Tool Call
Tool: order_lookup
Input: {"order_id": "12345"}
Output: {"status": "shipped", "eta": "tomorrow"}
Step 3: LLM Call
Agent thinks: "Order is shipped, arriving tomorrow"
Response: {"action": "final_answer", "answer": "Your order is shipped..."}
Multi-Turn Testing
Playground maintains conversation context:
User: "What's the weather in NYC?"
Agent: "It's 72°F and sunny"
User: "How about Boston?"
Agent: "Boston is 65°F and cloudy"
API Usage
Use agents programmatically in your application.
Execute Agent
Endpoint: POST /api/agents/{agent_id}/execute
import requests
import time
API_KEY = "mlsk_your_key_here"
# Submit task
response = requests.post(
f"https://mlstack.io/api/agents/{agent_id}/execute",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
},
json={
"input": "What's the status of order #12345?",
"max_iterations": 5
}
)
execution_id = response.json()["execution_id"]
Poll for Results
Endpoint: GET /api/agents/executions/{execution_id}
while True:
result = requests.get(
f"https://mlstack.io/api/agents/executions/{execution_id}",
headers={"Authorization": f"Bearer {API_KEY}"}
)
data = result.json()
if data["status"] == "completed":
print(f"Answer: {data['final_output']}")
break
elif data["status"] == "failed":
print(f"Error: {data['error_message']}")
break
time.sleep(1)
Multi-Turn Conversations
Use session_id for contextual conversations:
# First message
response1 = requests.post(
f"https://mlstack.io/api/agents/{agent_id}/execute",
headers={"Authorization": f"Bearer {API_KEY}"},
json={"input": "What's the weather in NYC?"}
)
session_id = response1.json()["session_id"]
# Follow-up message (agent remembers context)
response2 = requests.post(
f"https://mlstack.io/api/agents/{agent_id}/execute",
headers={"Authorization": f"Bearer {API_KEY}"},
json={
"input": "Should I bring an umbrella?",
"session_id": session_id
}
)
{
"execution_id": "01HW9X...",
"session_id": "01HW9Y...",
"agent": {
"id": "01HW8Z...",
"name": "customer-support"
},
"status": "completed",
"input_text": "What's the status of order #12345?",
"final_output": "Order #12345 is shipped and will arrive tomorrow",
"steps": [
{
"step": 1,
"type": "llm_call",
"response": {"action": "order_lookup", "order_id": "12345"}
},
{
"step": 2,
"type": "tool_call",
"tool_name": "order_lookup",
"tool_input": {"order_id": "12345"},
"tool_output": {"status": "shipped", "eta": "tomorrow"}
}
],
"metrics": {
"duration": 2.5,
"iteration_count": 1,
"llm_call_count": 2,
"tool_call_count": 1
}
}
Best Practices
System Prompts
Clear Instructions:
✅ "You are a customer support agent. Use order_lookup to find
order details. Always verify customer information before
taking action."
❌ "You help customers."
Mention Tools:
"Use the available tools to help users. For weather questions,
use get_weather. For order questions, use order_lookup."
Set Boundaries:
"Only access customer data when the user provides their order ID.
Never make up information. If you can't find data, say so."
Descriptive Names:
✅ "order_lookup" - Clear what it does
❌ "get_data" - Too generic
Detailed Descriptions:
✅ "Look up customer order details by order ID. Returns status,
items, shipping info, and tracking number."
❌ "Get order info"
Type Safety:
{
"order_id": {
"type": "string",
"pattern": "^[0-9]{5}$",
"description": "5-digit order ID"
}
}
Error Handling
Return Clear Errors:
{
"error": "Order not found",
"order_id": "12345",
"suggestion": "Please verify the order ID"
}
Handle Gracefully:
"I couldn't find order #12345. Please check that the order ID
is correct and try again."
- Limit iterations - Default of 5 is usually enough
- Optimize tools - Fast APIs = faster agents
- Cache common queries - Reduce redundant tool calls
- Monitor usage - Track which tools are used most
Debugging
- Check system prompt mentions the tools
- Verify tool descriptions are clear
- Ensure tool parameters are well-defined
- Test tool URLs directly (curl/Postman)
- Check authentication headers
- Verify parameter formats match API requirements
- Review error messages in execution steps
Max Iterations Reached?
- Increase max_iterations setting
- Simplify the task
- Improve tool descriptions
- Check if tools are returning useful data
- Make tool descriptions more specific
- Add examples in system prompt
- Use parameter descriptions to clarify usage
Next Steps