REST API

Agent Kernel provides a built-in REST API server for agent interaction.

Starting the API Server

from agentkernel.api import RESTAPI

if __name__ == "__main__":
    RESTAPI.run()

Or from CLI:

python my_agent.py

Endpoints

POST /run

Execute an agent with a message.

Request:

{
  "agent": "assistant",
  "prompt": "What is 2 + 2?",
  "session_id": "user-123"
}

Response:

{
  "result": "2 + 2 equals 4.",
  "session_id": "user-123"
}

GET /agents

List all available agents.

Response:

{
  "agents": ["assistant", "math", "code"]
}

GET /health

Health check endpoint.

Response:

{
  "status": "ok"
}

Error Handling

400 Bad Request:

{
  "error": "Missing required field: agent"
}

500 Internal Server Error:

{
  "error": "Agent execution failed",
  "session_id": "session-x"
}

Passing additional context

You can pass additional properties in the request body. These will be automatically passed to the PreHooks with the key name, to be handled by the your code. These will not be passed to the Agents as input.

In the following example, user_id (string) and additional_context (dict) will be passed PreHooks as two AgentRequestAny objects with names "user_id"and "additional_context". A complete example is provided here

{
  "agent": "assistant",
  "prompt": "What is 2 + 2?",
  "session_id": "user-123",
  "user_id" : "anne",
  "additional_context": { "ui_selections"=[], profile_name="custom"}
}

Please study the Hooks documentation for the use of hooks to implement various use cases.

Passing images and files

Agent Kernel supports sending images and files to agents in two ways: via JSON body with base64-encoded data, or as multipart form data for larger files.

Current Limitation

Currently, passing images and files only work with OpenAI SDK & Google ADK. Other implementations will be provided in future

NOTE: Directly passing image is not recommended. It is advised to save images in Agent accessible storage and pass the URI. This can be done directly from the client side or via hooks. i.e. PreExecution Hooks can intercept the requests, detect images/files and store and modify the request to contain the URIs

Supported file types

• Images: JPEG, PNG, GIF, WebP, and other image formats
• Documents: PDF, TXT, CSV, DOC, DOCX, and other document formats

Supported file formats will differ for different frameworks. Please refer to the relevant documentation.

• OpenAI Agents

The MIME type is automatically detected from uploads in multipart mode, or should be explicitly specified in the JSON body for base64-encoded data. Or it can be in the base64 string itself at the start of the string ( E.g. "data:application/pdf;base64,.........").

Option 1: JSON Body (Base64 Encoded)

For smaller files and images, you can include them directly in the JSON request body as base64-encoded strings or direct URLs to publicly accessible files. Base64 strings works well for files under a few MB. The encoding increases the size at least by 33%.

Request with images:

{
  "agent": "assistant",
  "prompt": "Can you describe this image?",
  "session_id": "user-123",
  "images": [
    {
      "name": "photo.jpg",
      "mime_type": "image/jpeg",
      "image_data": "base64_encoded_image_data_here"
    }
  ]
}

Request with files:

{
  "agent": "assistant",
  "prompt": "What is the deadline mentioned in this document?",
  "session_id": "user-123",
  "files": [
    {
      "name": "document.pdf",
      "mime_type": "application/pdf",
      "file_data": "base64_encoded_pdf_data_here"
    }
  ]
}

Request with both images and files:

{
  "agent": "assistant",
  "prompt": "Analyze this document and image",
  "session_id": "user-123",
  "files": [
    {
      "name": "report.pdf",
      "mime_type": "application/pdf",
      "file_data": "base64_encoded_pdf_data_here"
    }
  ],
  "images": [
    {
      "name": "chart.png",
      "mime_type": "image/png",
      "image_data": "base64_encoded_image_data_here"
    }
  ]
}

Option 2: Multipart Form Data

For larger files, use the /run-multipart endpoint with multipart/form-data. This approach is more efficient for files larger than a few MB and avoids base64 encoding overhead.

Endpoint: POST /run-multipart

Request parameters:

• prompt (required): Text prompt for the agent
• agent (optional): Agent name
• session_id (optional): Session identifier
• files (optional): One or more file uploads (PDF, CSV, TXT, etc.)
• images (optional): One or more image uploads (JPEG, PNG, etc.)

Example using curl:

curl -X POST http://localhost:8000/run-multipart \
  -F "prompt=What is the deadline in this document?" \
  -F "agent=assistant" \
  -F "session_id=user-123" \
  -F "files=@document.pdf" \
  -F "images=@photo.jpg"

Example using Python requests:

import requests

with open("document.pdf", "rb") as pdf_file, open("photo.jpg", "rb") as image_file:
    files = {
        "files": ("document.pdf", pdf_file, "application/pdf"),
        "images": ("photo.jpg", image_file, "image/jpeg")
    }
    data = {
        "prompt": "Analyze this document and image",
        "agent": "assistant",
        "session_id": "user-123"
    }
    
    response = requests.post(
        "http://localhost:8000/run-multipart",
        data=data,
        files=files
    )
    print(response.json())

Response (same for both methods):

{
  "result": "The deadline mentioned in the document is December 12, 2025.",
  "session_id": "user-123"
}

A detailed example with tests are provided here

Choosing the right method

• Use JSON body for:

  • Small files (< 1-2 MB)
  • When you already have base64-encoded data
  • Simple API integration scenarios

• Use multipart form data for:

  • Large files (> 1-2 MB)
  • Multiple file uploads
  • Better performance and lower memory usage
  • Direct file uploads from forms or file systems

Custom Routes

Agent Kernel REST API allows the users to add custom routes to the existing REST server by two ways. This is a support functionality that would avoid users from maintaining a separate REST server for other application work, and exposes an endpoint with a configurable prefix /custom by default.

Option 1

Add a route directly

from agentkernel.api import RESTAPI
from fastapi import APIRouter

# Optional custom route to add your own endpoints
router = APIRouter()


@router.post("/deposit")
async def run(req: dict):
    amount = req.get("amount")
    return {"result": f"Deposited ${amount} over the counter"}


RESTAPI.add(router=router)
# End of optional code block for REST API mode

if __name__ == "__main__":
    RESTAPI.run()

Option 2

Add the default Agent REST API handler

class CustomRESTRequestHandler(AgentRESTRequestHandler):

    def __init__(self):
        super().__init__()


    def get_router(self) -> APIRouter:
        router = super().get_router()

        @router.get("/custom")
        def custom():
            return custom_request_handler()

        return router

if __name__ == "__main__":
    RESTAPI.run(handler=CustomRESTRequestHandler())

Streaming

Support for streaming responses will be available soon

Best Practices

• Use unique session IDs per conversation
• Handle errors gracefully
• Implement rate limiting in production
• Use HTTPS in production
• Add authentication
• Monitor API performance