Skip to content

Repository Structure

A typical Codeligence Agents repository has the following files and directories:

.
├─ .env.sample                # A sample configuration file containing environment variables
├─ .env                       # Your actual environment variables (not committed to source control)
├─ Dockerfile                 # Docker build file for the Codeligence Agents image
├─ requirements.txt           # Python dependencies for the server & the agents
├─ README.md                  # Development and deployment notes
├─ PROMPT_CODE.md             # Detailed instructions and examples for building Pydantic AI agents
└─ src/
   ├─ server.py               # The FastAPI server that orchestrates agent calls
   ├─ services/
   │  └─ agent_service.py     # Logic for detecting available agents and integrations
   ├─ utils/
   │  ├─ codeligence_utils.py # Common helper functions for interacting with Codeligence
   │  ├─ pydanticai_utils.py  # Utilities for using the Pydantic AI framework
   │  └─ crewai_utils.py      # Utilities for using the CrewAI framework (optional)
   ├─ agents/                 # Your agents go here! Each in its own subfolder
   │  └─ <agent name>/
   │     ├─ agent.py          # Required: main agent script implementing `run(...)`
   │     └─ integration.py    # Optional: additional logic not requiring user chat
   └─ rundev.py               # Local development/testing script

Environment Files

  • .env.sample: a sample list of environment variables. Copy this to .env and fill in your credentials or service URLs (e.g., CODELIGENCE_URL, CODELIGENCE_TOKEN, OPENWEATHER_API_KEY, etc.).
  • .env: your real environment variables (credentials). Typically not committed to source control.

Key Server Files

  • server.py: the FastAPI server receiving requests from the Codeligence Platform. It exposes:
  • GET /list: lists available (enabled) agents.
  • POST /run: runs a given agent’s run(message, history, …) method in a subprocess.
  • agent_service.py: discovers agents (by looking for agent.py) and integrations (by looking for integration.py) in the /src/agents directory.
  • rundev.py: a small script you can locally run to test your agent in isolation without going through Docker or the full platform.

Utility Modules

  • codeligence_utils.py:
  • Functions like codeligence_report_status(), codeligence_report_task_output(), codeligence_report_citations(), codeligence_report_buttons().
  • Use these to send real-time updates (status messages, partial outputs, citations, interactive buttons) back to the user’s chat.
  • pydanticai_utils.py:
  • Simplifies usage of the Pydantic AI framework with the Codeligence models (codeligence_pydantic_llm_model(...)).
  • Converts chat history from the Codeligence format to Pydantic AI messages.
  • crewai_utils.py:
  • Similar tools for the CrewAI framework (if you want to use CrewAI instead of Pydantic AI).

Agents Folder

  • /src/agents:
    Each agent is stored in its own subdirectory. If you create an agent named Weather Assistant, you might have: 
    src/agents/weather/
   ├─ agent.py        # Required
   └─ integration.py  # Optional
  • agent.py: Must implement at least: 
    def run(message: str, history: Optional[List[Message]] = None, button: ButtonResponse = None):
    # Agent logic goes here

def get_config():
    return AgentInfo(enabled=True, name="My Agent")
  • run(...) is the main entry point the server calls.

  • get_config() returns an AgentInfo object that indicates whether the agent is enabled and what name it exposes.

  • integration.py: Optionally implement certain functions that run in the background or on schedules (not triggered by user chat). Typically used for ETL tasks, data updates, or indexing. If you add get_config() here returning an IntegrationInfo, the server will recognize and run it.