# Create your first agent

Initialize an agent project and prepare its first deployable behavior.

By the end of this guide, you will have a valid Salambo project with instructions, a model, built-in tools, and deployment credentials.

## Prerequisites

* A Salambo workspace
* Node.js 22 or later
* The Salambo CLI
* A [scoped Salambo API key](/docs/guides/create-api-key)
* A provider key such as `OPENAI_API_KEY`

For this workflow, the Salambo key needs `agents:read`, `agents:write`,
`env_vars:read`, `env_vars:write`, `models:read`, `run:read`, and `run:write`.

## 1. Create the project

```bash
salambo init support-agent
cd support-agent
```

The command clones the immutable starter version compatible with the installed CLI. It changes only the project name and agent slug; the template owns the runtime defaults.

## 2. Understand the minimum project

```text
support-agent/
├── .pi/
│   ├── settings.json
│   ├── SYSTEM.md
│   ├── skills/
│   ├── prompts/
│   └── extensions/
├── sandbox/
│   └── workspace/
└── salambo.yaml
```

Salambo owns the model loop and run lifecycle. Your project supplies instructions, declared resources, extensions, workspace seed files, and deployment configuration.

## 3. Write the first instruction

Replace `.pi/SYSTEM.md` with:

```markdown
# Customer support agent

Help support engineers investigate customer reports.

- Read available workspace files before answering.
- Separate confirmed facts from assumptions.
- Save investigation notes in `/workspace/notes.md`.
- Never include credentials or secret values in a response.
```

## 4. Select the model and tools

Edit `.pi/settings.json`:

```json
{
  "defaultProvider": "openai",
  "defaultModel": "gpt-5.2",
  "defaultThinkingLevel": "medium"
}
```

The hosted runtime supplies Pi's `read`, `write`, `edit`, and `bash` tools. Tools discovered from `.pi/extensions/` also start active. Shell utilities such as `grep`, `find`, and `ls` run through `bash`; they are not separate Pi tools.

## 5. Authenticate the CLI

```bash
salambo auth set --api-url https://YOUR_SALAMBO_HOST
salambo auth set --key "$SALAMBO_API_KEY"
salambo auth whoami
```

The CLI stores the selected profile locally. Do not commit API keys.

## 6. Provide the model credential

The generated `salambo.yaml` reads the provider key from your environment:

```bash
export OPENAI_API_KEY="YOUR_PROVIDER_KEY"
```

Secret values belong in the deployer's environment, never in `salambo.yaml` or agent instructions.

## 7. Validate the project

```bash
salambo doctor
salambo manifest --path . --json
```

`doctor` checks the hosted source-deployment contract, compiled manifest, managed packages, authentication, and declared secrets. `manifest` imports and validates agent resources and extension declarations without deploying them.

You now have a deployable agent project. Next, understand the [project structure](/docs/agent-development/project-structure), then [write production instructions](/docs/agent-development/skills-prompts).