> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyzr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Structure

> Directory layout and agent.yaml manifest reference for GitAgent.

GitAgent follows the [OpenGAP](../opengap/directory-structure) directory convention. Every GitAgent repository has a predictable structure that the runtime discovers by walking the directory tree.

## Directory layout

```
my-agent/
├── agent.yaml              ← agent manifest (required)
├── skills/                 ← skill modules
│   ├── search_web.py
│   ├── read_file.py
│   └── summarize/
│       ├── __init__.py
│       └── helpers.py
├── hooks/                  ← lifecycle hooks
│   ├── before_skill.py
│   ├── after_skill.py
│   └── on_error.py
├── flows/                  ← SkillsFlow definitions
│   ├── research.yaml
│   └── report.yaml
├── plugins/                ← runtime plugins
│   └── my_output_plugin.py
├── memory/                 ← memory configuration
│   └── config.yaml
└── tests/                  ← skill tests
    └── test_search_web.py
```

All top-level directories are optional except `agent.yaml`.

## `agent.yaml` reference

```yaml theme={null}
# Required fields
name: my-agent               # unique agent identifier
version: "1.0.0"             # semver

# Optional metadata
description: "Researches topics and writes summaries"
author: "Your Name"
tags: [research, writing]

# Model configuration
model:
  provider: openai           # openai | anthropic | azure-openai | ollama | lyzr
  name: gpt-4o               # model name
  temperature: 0.0           # 0.0–2.0
  max_tokens: 4096           # max output tokens
  timeout: 60                # seconds

# System prompt
system_prompt: |
  You are a research assistant. When asked a question, search for 
  information and provide a well-cited summary.

# Memory configuration
memory:
  enabled: true
  provider: local            # local | lyzr | custom
  max_history: 20            # number of past turns to keep

# Skills discovery
skills:
  path: skills/              # directory to scan (default: skills/)
  include: ["*.py"]          # glob patterns to include
  exclude: ["*_test.py"]     # glob patterns to exclude

# Hooks
hooks:
  path: hooks/               # directory to scan (default: hooks/)

# Flows
flows:
  path: flows/               # directory to scan (default: flows/)

# Execution settings
execution:
  max_iterations: 20         # max agent loop iterations
  timeout: 300               # total run timeout in seconds
  parallel_skills: false     # allow parallel skill calls

# Telemetry
telemetry:
  enabled: true
  endpoint: ${LANGSHIP_ENDPOINT}
  api_key: ${LANGSHIP_API_KEY}
```

## Multiple agents in one repo

A monorepo can contain multiple agents in subdirectories:

```
monorepo/
├── agents/
│   ├── researcher/
│   │   ├── agent.yaml
│   │   └── skills/
│   └── writer/
│       ├── agent.yaml
│       └── skills/
└── shared/
    └── skills/              ← skills shared across agents
```

Reference shared skills from `agent.yaml`:

```yaml theme={null}
skills:
  path:
    - skills/                # agent-specific skills
    - ../../shared/skills/   # shared skills
```

## Environment variables in `agent.yaml`

Any value in `agent.yaml` can reference an environment variable using `${VAR_NAME}` syntax:

```yaml theme={null}
model:
  provider: openai
  name: ${AGENT_MODEL:-gpt-4o}   # default to gpt-4o if not set
```

## Validating your structure

```bash theme={null}
gitagent validate
```

Checks:

* `agent.yaml` schema is valid
* All referenced skill paths exist
* No circular flow dependencies
* Hooks have the correct function signatures
* Required environment variables are set