Quick start
Start your first agent session from the CLI, Python, TypeScript, or curl.
Get started
Install the CLI or an SDK:
1
curl -fsSL https://ellipsis.dev/install.sh | sh
1
pip install ellipsis-dev
1
npm install @ellipsis-dev/sdk
Sign in with device auth. The CLI opens your browser to approve the login:
Shell
1
el auth login
For CI, the SDKs, and curl, export an API key from API > API keys in the dashboard:
Shell
1
export ELLIPSIS_API_TOKEN="ellipsis_key_..."
Start an agent session
Start the classify-change agent:
1
el agent start classify-change --input '{"description": "Reject expired reset tokens"}'
1
import os
2
3
from ellipsis import Ellipsis
4
5
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
6
change = {"description": "Reject expired reset tokens"}
7
response = client.agents.start("classify-change", input=change)
8
print(response.session.id)
1
import { Ellipsis } from '@ellipsis-dev/sdk';
2
3
const apiKey = process.env.ELLIPSIS_API_TOKEN!;
4
const client = new Ellipsis({ apiKey });
5
const input = { description: 'Reject expired reset tokens' };
6
const { session } = await client.agents.start('classify-change', { input });
7
console.log(session.id);
1
curl https://api.ellipsis.dev/v1/agents/classify-change/sessions -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" -H "Content-Type: application/json" -d '{"input": {"description": "Reject expired reset tokens"}}'
Typed input and output defines it. An agent with no input schema takes prompt instead of input.
Wait for it to finish:
1
el session get <session-id> --watch
1
handle = client.sessions.handle("your-session-id")
2
session = handle.wait()
3
print(session.turn.status)
1
const handle = await client.sessions.handle('your-session-id');
2
const turn = await handle.wait();
3
console.log(turn?.status);
1
# Repeat until session.turn.status is final
2
curl https://api.ellipsis.dev/v1/sessions/your-session-id -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
wait and --watch return when status is completed, failed, stopped, or cancelled. --watch exits 0 only for completed.
Read the output:
1
print(client.sessions.output("your-session-id"))
1
console.log(await client.sessions.output('your-session-id'));
1
curl https://api.ellipsis.dev/v1/sessions/your-session-id/output -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"
It matches the agent's output.json_schema:
JSON
1
{
2
"category": "bugfix",
3
"reason": "Rejecting expired reset tokens closes a validation gap."
4
}
Errors and retries
- Errors return
{"error": {"code": "...", "message": "..."}}. Branch oncode, notmessage. - Retry
429afterRetry-After, and5xxwith backoff. - A start that times out can still succeed. Tag sessions with
metadataand list recent sessions before you retry.
Pagination
- Paginated routes take
limitandcursor. - Pass
next_cursoruntilhas_moreisfalse. - SDK iterators fetch every page.