This tutorial walks you through integrating AMAS agents into your applications using the REST API. You’ll learn how to create agents, manage sessions, execute messages, and handle responses programmatically.
Prerequisites
Base URL
All API requests use: https://api-be.atthene.com/api/v1
Authentication
Include your API key in the x-api-key header with every request
Never expose your API key in client-side code or public repositories. Use environment variables or secure credential storage.
Agent Setup and Knowledge Base Management
Learn how to create agents, manage sessions, and build knowledge bases for enhanced AI responses.
Part 1: Generate Answers
Create sessions from agent configurations and execute user messages to get AI responses.
Create Session from Agent Configuration
curl -X POST https://api-be.atthene.com/api/v1/sessions/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Basic Dynamic Agent Test",
"description": "Test configuration for basic dynamic agent loading",
"save_messages": true,
"persistent_state": true,
"agents": [
{
"name": "test_basic_agent",
"agent_type": "llm_agent",
"description": "A simple sessional agent for testing dynamic loading",
"prompt_config": {
"system_prompt": "You are a helpful AI assistant."
},
"llm_config": {
"temperature": 1.0,
},
"knowledge_bases": [],
"streaming_config": {
"show_output_to_user": true
}
}
],
"edges": [
{
"from": "__start__",
"to": "test_basic_agent"
},
{
"from": "test_basic_agent",
"to": "__end__"
}
],
"entry_point": "test_basic_agent"
}'
{
"success": true,
"session_id": "820d6859-60d0-48f2-a4fc-c8dad229d311",
"config_hash": "object:f1f2510eaad449aebddc23690cb29630cebd83058d09e29c7f57969fb2177c73:u:anon"
}
Execute User Message on Session ID
Replace SESSION_ID with the actual session ID from the previous response:
curl -X POST https://api-be.atthene.com/api/v1/runtime/session_abc123/execute/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "Hello! I need help with my account."
}'
{
"response": {
"content": "Hello! I'd be happy to help you with your account. What specific issue are you experiencing?",
"role": "assistant"
},
"session_id": "session_abc123",
"message_id": "msg_def456"
}
Continue Conversation
Send additional messages to maintain conversation context:
curl -X POST https://api-be.atthene.com/api/v1/runtime/session_abc123/execute/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "How do I reset my password?"
}'
Part 2: Create Knowledge Bases
TODO: Replicate & Adjust documentation
Upload data, create collections, and build knowledge bases for your agents to use.
Upload Data
Upload files to be used in your knowledge base:
curl -X POST https://api-be.atthene.com/api/v1/files/ \
-H "x-api-key: YOUR_API_KEY" \
-F "file=@/path/to/document.pdf" \
-F "tags=manual,product"
{
"id": "file_456",
"original_filename": "document.pdf",
"file_type": "document",
"size_bytes": 2048576,
"status": "uploading",
"tags": ["manual", "product"],
"created_at": "2025-01-15T10:30:00Z"
}
Create Collections
Create a collection to organize related documents:
curl -X POST https://api-be.atthene.com/api/v1/collections/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Product Documentation",
"description": "All product manuals and guides"
}'
{
"id": "coll_456",
"name": "Product Documentation",
"description": "All product manuals and guides",
"status": "pending",
"progress": 0,
"data_source_count": 0,
"total_size": 0,
"created_at": "2025-01-15T10:30:00Z"
}
Add Files to Collection
Add uploaded files to your collection:
curl -X POST https://api-be.atthene.com/api/v1/collections/coll_456/files/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"file_ids": ["file_456", "file_789"]
}'
{
"success": true,
"added": 2,
"failed": 0,
"results": [
{
"file_id": "file_456",
"status": "added"
},
{
"file_id": "file_789",
"status": "added"
}
]
}
Create Knowledge Base
Create a knowledge base from your collections:
curl -X POST https://api-be.atthene.com/api/v1/knowledge-bases/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Product Knowledge Base",
"description": "Product documentation and guides",
"processing_engine": "milvus",
"collections": ["coll_456"]
}'
{
"id": "kb_789",
"name": "Product Knowledge Base",
"description": "Product documentation and guides",
"processing_engine": "milvus",
"status": "pending",
"progress": 0,
"collection_count": 1,
"success_rate": 0,
"created_by_name": "John Doe",
"created_at": "2025-01-15T10:30:00Z"
}
Part 3: Insert Knowledge Base into Agent Configuration
Add your knowledge base to the agent configuration for enhanced responses.
Create Session with Knowledge Base
curl -X POST https://api-be.atthene.com/api/v1/sessions/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Documentation Agent",
"agent_type": "llm_agent",
"system_prompt": "You are a documentation assistant. Use the knowledge base to answer questions accurately.",
"llm_config": {
"model": "gpt-4o",
"temperature": 0.7
},
"knowledge_bases": [
{
"name": "gtsre",
"knowledge_base_type": "milvus",
"id": "kb_789",
"config": {
"top_k": 5,
"search_ef": 64,
"metric_type": "COSINE"
}
}
]
}'
Test Knowledge Base Integration
Send a question that requires knowledge base lookup:
curl -X POST https://api-be.atthene.com/api/v1/runtime/session_xyz123/execute/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "How do I configure authentication in the product?"
}'
Common Errors
| Status Code | Error | Solution |
|---|
400 | Invalid configuration | Validate config with /agent/validate/ endpoint |
401 | Unauthorized | Check API key is correct and not expired |
404 | Session not found | Verify session ID exists, may have been deleted |
429 | Rate limit exceeded | Implement exponential backoff and retry logic |
500 | Internal server error | Check request format, contact support if persists |
Next Steps
