API Reference

This section contains automatically generated API documentation from the source code. All classes, methods, and functions are documented with their signatures, parameters, and return types.

Overview

AgentShip’s API is built on FastAPI and provides:

• RESTful endpoints for agent interactions

• Auto-generated documentation via Swagger/ReDoc

• Type-safe models using Pydantic

• Session management for conversation persistence

• Error handling with detailed error messages

Main Endpoints

POST /api/agents/chat

Chat with any registered agent. This is the primary endpoint for agent interactions.

GET /health

Health check endpoint to verify service status.

GET /

Root endpoint with welcome message.

Core Modules

The following pages document the core API components:

• BaseAgent - Base agent class

• AgentConfig - Agent configuration

• Models - Data models

• Modules - Supporting modules

Base Agent

The BaseAgent class is the foundation for all agents. It provides:

• Agent initialization and configuration

• Session management

• LLM integration

• Response parsing

• Tool support

See BaseAgent for complete documentation.

Agent Configuration

The AgentConfig class handles:

• Loading configuration from YAML files

• Validating agent settings

• Managing LLM provider configurations

See AgentConfig for complete documentation.

Models

Pydantic models for type-safe data:

• TextInput / TextOutput: Basic text I/O

• AgentChatRequest / AgentChatResponse: API request/response

• FeatureMap: Feature configuration

• Artifact: File attachments

See Models for complete documentation.

Modules

Supporting modules for agent functionality:

• SessionManager: Manages conversation sessions

• AgentConfigurator: Handles agent configuration

• ResponseParser: Parses and formats agent responses

• SessionServiceFactory: Creates session services

See Modules for complete documentation.

Usage Examples

Basic Agent Chat

from src.service.models.base_models import AgentChatRequest

request = AgentChatRequest(
    agent_name="my_agent",
    user_id="user-123",
    session_id="session-456",
    query="Hello!",
    features=[]
)

response = await agent.chat(request)

Creating an Agent

from src.all_agents.base_agent import BaseAgent
from src.agent_framework.configs.agent_config import AgentConfig
from src.service.models.base_models import TextInput, TextOutput

config = AgentConfig.from_yaml("path/to/config.yaml")
agent = MyAgent(
    agent_config=config,
    input_schema=TextInput,
    output_schema=TextOutput
)

Session Management

Sessions are automatically managed:

• New sessions are created on first use

• Sessions persist conversation history

• Can use PostgreSQL or in-memory storage

Error Handling

All endpoints return appropriate HTTP status codes:

• 200: Success

• 404: Agent not found

• 422: Validation error

• 500: Internal server error

Error responses include detailed messages:

{
  "detail": "Agent 'invalid_agent' not found. Available agents: ['my_agent', 'other_agent']"
}