Skip to main content
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

1

Get API Key

Generate an API key from the Atthene Agent Studio settings
2

Base URL

All API requests use: https://api-be.atthene.com/api/v1
3

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"
  }'
Response: 
{
    "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: 
{
  "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"
Response: 
{
  "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"
  }'
Response: 
{
  "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"]
  }'
Response: 
{
  "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"]
  }'
Response: 
{
  "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?"
  }'
The agent will automatically search the knowledge base and provide an answer based on the uploaded documentation.

​
Common Errors

Status CodeErrorSolution
400Invalid configurationValidate config with /agent/validate/ endpoint
401UnauthorizedCheck API key is correct and not expired
404Session not foundVerify session ID exists, may have been deleted
429Rate limit exceededImplement exponential backoff and retry logic
500Internal server errorCheck request format, contact support if persists

​
Next Steps

API Reference

Complete API endpoint documentation

Authentication

Detailed authentication guide

Chatbot Integration

Build real-time chat interfaces

YAML Configuration

Learn about agent configuration