# How To Create A New Agent In Chanakya v2

This guide documents exactly what is needed to add a new sub-agent in `backend/chanakya/` the same way `gmail` and `jira` were added.

## Goal

When adding a fresh agent, you should have:
- A repeatable checklist of required inputs and code changes.
- A clear path to automate scaffolding and wiring.

## 1) Inputs Required Before You Start (Agent Intake Checklist)

Collect these first.

### Identity and routing
- `agent_key` (lowercase slug): e.g. `salesforce`
- `agent_name` (display name): e.g. `Salesforce Agent`
- `agent_description` (A2A card description)
- `module_path`: `backend.chanakya.<agent_key>.agent:app`
- `host_env_var`: `<AGENT_KEY_UPPER>_AGENT_HOST`
- `port_env_var`: `<AGENT_KEY_UPPER>_AGENT_PORT`
- `default_port`: next free port (e.g. `8003`)

### Agent behavior
- System instructions/persona for the agent
- Tool list and contracts:
  - Tool names
  - Input params and validation rules
  - Output format expectations
  - “No results” behavior

### Chat/UI and storage
- `hero_title` and `hero_subtitle` for `/chat`
- DB path folder under `data/<agent_key>/chat_history.db`

### Runtime/deployment
- Docker service name: `<agent_key>-agent`
- Container image name: `chanakya/<agent_key>-agent:latest`
- Healthcheck endpoint: `/.well-known/agent-card.json`
- Exposed container port

### Orchestration
- Should Chanakya query this agent directly?
- If yes:
  - Add `ask_<agent_key>` tool in hub.
  - Update hub instructions to include the new data source.

## 2) Files To Create (New Agent Package)

Create a new folder:
- `backend/chanakya/<agent_key>/`

Add files:
- `backend/chanakya/<agent_key>/agent.py`
- `backend/chanakya/<agent_key>/mock_data.py` (or real client/service module)
- `backend/chanakya/<agent_key>/__init__.py`
- `backend/chanakya/<agent_key>/Dockerfile`
- `backend/chanakya/<agent_key>/requirements.txt`

Use `gmail` or `jira` package as the base template.

## 3) Files To Update (Current v2 Reality)

Even though `config.py` suggests only registry changes, current code still requires multi-file wiring.

### A) Register endpoint
Update:
- `backend/chanakya/config.py`

Add a new `AGENT_REGISTRY["<agent_key>"] = AgentEndpointConfig(...)` entry.

### B) Wire into hub orchestration
Update:
- `backend/chanakya/rt_agent/agent.py`

Add:
- `<AGENT_KEY>_AGENT_URL = AGENT_REGISTRY["<agent_key>"].url`
- `@chanakya.tool async def ask_<agent_key>(ctx: RunContext[RequestContext], question: str) -> str`
- Hub instruction text to mention the new source.

### C) Local launcher targets
Update:
- `backend/chanakya/Makefile`

Add:
- `<AGENT_KEY>_AGENT_HOST` and `<AGENT_KEY>_AGENT_PORT`
- `<agent_key>` target
- `agents` target launch entry
- help text entries

### D) Docker Compose services
Update:
- `docker-compose.yml`
- (optional, if needed for local pylogue dev) `docker-compose.override.yml`

Add:
- New `<agent_key>-agent` service block
- Port mapping and data volume (`./data/<agent_key>:/data`)
- Healthcheck
- Hub env vars for host/port
- `depends_on` for the hub service

## 4) Validation Checklist (Definition of Done)

Run and verify:

1. Agent boots standalone
- Uvicorn starts with no import/runtime errors.

2. Agent card is reachable
- `http://localhost:<port>/.well-known/agent-card.json` returns success.

3. Chat UI works
- `http://localhost:<port>/chat` loads and stores history in `data/<agent_key>/`.

4. Tool behavior is correct
- Known query returns expected shaped output.
- Unknown query returns single clear “nothing found” response (no retry loops).

5. Hub integration works
- Chanakya can invoke `ask_<agent_key>` and includes this source in synthesis.

6. Compose stack healthy
- New service reports healthy and hub starts after dependencies.

## 5) What Can Be Automated

Yes, most of this can be automated safely.

## Recommended automation scope (v1)

Build a scaffold command (example: `scripts/new_agent.py`) that:

1. Generates package from templates
- Creates `backend/chanakya/<agent_key>/` with `agent.py`, `__init__.py`, `Dockerfile`, `requirements.txt`, and starter data/tool file.

2. Patches registry
- Adds `AgentEndpointConfig` entry in `backend/chanakya/config.py`.

3. Patches hub
- Adds URL constant, `ask_<agent_key>` tool, and updates hub instruction source list in `backend/chanakya/rt_agent/agent.py`.

4. Patches Makefile and Compose
- Adds host/port vars, run targets, compose service, hub env vars, and dependency wiring.

5. Creates data folder
- Ensures `data/<agent_key>/` exists.

6. Prints post-generation test commands
- Card URL check, chat URL check, and one hub invocation check.

## Suggested script inputs

- `--key salesforce`
- `--name "Salesforce Agent"`
- `--description "..."`
- `--port 8003`
- `--hero-subtitle "..."`
- `--tool-mode mock|real`

## Safety rules for automation

- Idempotent patches (no duplicate insertions).
- Abort with clear message on conflicting edits.
- Support `--dry-run` to preview diffs.
- Generate a summary report of files created/modified.

## 6) Suggested Next Improvements

To reduce future manual edits, refactor the hub to dynamically register `ask_<agent_key>` tools from `AGENT_REGISTRY` instead of hardcoding Gmail/Jira.

That would make new-agent onboarding close to: scaffold package + add one registry entry.