Building Agents

Two files. That’s an agent.

AgentShip auto-discovers all agents in src/all_agents/ at startup. No registration step, no routing config — just a YAML and a Python class.

The Two Files

main_agent.yaml — everything infrastructure:

agent_name: my_agent
llm_provider_name: openai
llm_model: gpt-4o
temperature: 0.4
execution_engine: adk        # or langgraph — Python class is unchanged either way
description: A helpful assistant
instruction_template: |
  You are a helpful assistant that answers questions clearly.

main_agent.py — your agent logic:

from src.all_agents.base_agent import BaseAgent
from src.service.models.base_models import TextInput, TextOutput
from src.agent_framework.utils.path_utils import resolve_config_path

class MyAgent(BaseAgent):
    def __init__(self):
        super().__init__(
            config_path=resolve_config_path(relative_to=__file__),
            input_schema=TextInput,
            output_schema=TextOutput,
        )

Restart the server — the agent appears in Studio and the API. No other step.

How Discovery Works

1. AgentShip scans src/all_agents/ for main_agent.yaml files at startup

2. Each YAML’s agent_name becomes the registry key

3. The corresponding Python class is imported and instantiated

4. The agent is registered and available immediately at /api/agents/chat

The registry key is always agent_name from YAML — not the class name, not the directory name.

Execution Engines

Set execution_engine in YAML. Your Python class never changes.

Engine	Config value	Streaming	When to use
Google ADK	adk	Event-based	Default; most agents
LangGraph + LiteLLM	langgraph	Token-by-token	When you need real streaming

Swap engines by changing one line:

- execution_engine: adk
+ execution_engine: langgraph

Agent Patterns

Three proven patterns are included as working examples:

• Single Agent — standalone agent for a focused task

• Orchestrator — main agent that delegates to sub-agents

• Tool Pattern — agent with custom Python function tools

Agent Lifecycle

1. Discovery — src/all_agents/ scanned on startup

2. Instantiation — Python class loaded, YAML config parsed

3. Tool setup — function tools and MCP connections established

4. Prompt build — tool documentation injected into system prompt

5. Request — chat() or stream() dispatches to the engine

6. Session — conversation history persisted to PostgreSQL

See Agent Configuration for all YAML fields, and Tools for adding function tools and MCP servers.