peter
4a5ea8944b
Adds docs/deployment.md, a platform-agnostic guide (any Linux host with Docker) built around a git-pull based fast-redeploy workflow, replacing the Proxmox-specific deploy/proxmox_llm_deploy.md which was also stale (old `persona` field, single-shared-token model predating multi-user auth). Also: drops the unused DAYBOOK_API_TOKEN from deploy/env.example, documents the new DELETE endpoint and capabilities `methods` field in docs/api.md and docs/agent_quickstart.md, and fixes CLAUDE.md's OpenCode note now that opencode.json is untracked (machine-specific MCP config). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
151 lines
4 KiB
Markdown
151 lines
4 KiB
Markdown
# Agent Quickstart
|
||
|
||
This is the shortest path for an agent to publish and retrieve artifacts from Daybook.
|
||
|
||
## 0. Get Your API Token
|
||
|
||
Log in to the app in a browser and copy your personal token from **Settings → Account**
|
||
(`http://127.0.0.1:8001/settings/account/`). Every artifact you post with it lands in your
|
||
feed, and only yours.
|
||
|
||
## 1. Check Capabilities
|
||
|
||
Also confirms your token is valid:
|
||
|
||
```powershell
|
||
Invoke-RestMethod "http://127.0.0.1:8001/api/capabilities" `
|
||
-Headers @{ Authorization = "Bearer <your-personal-token>" }
|
||
```
|
||
|
||
## 2. Publish Markdown
|
||
|
||
```powershell
|
||
$body = @{
|
||
source = "hermes-research"
|
||
source_type = "agent"
|
||
source_name = "Hermes Agent"
|
||
source_id = "hermes-local"
|
||
kind = "markdown"
|
||
title = "Agent Status Update"
|
||
content = "# Status Update`n`nThe agent completed its run successfully."
|
||
tags = @("status", "agent")
|
||
metadata = @{
|
||
run_id = "run-001"
|
||
model = "gpt-5.5"
|
||
}
|
||
} | ConvertTo-Json -Depth 5
|
||
|
||
$artifact = Invoke-RestMethod `
|
||
-Uri "http://127.0.0.1:8001/api/artifacts" `
|
||
-Method Post `
|
||
-Headers @{ Authorization = "Bearer <your-personal-token>" } `
|
||
-ContentType "application/json" `
|
||
-Body $body
|
||
|
||
$artifact
|
||
```
|
||
|
||
Open the artifact in the browser:
|
||
|
||
```powershell
|
||
$artifact.url
|
||
```
|
||
|
||
## 3. Publish HTML Fragment
|
||
|
||
```powershell
|
||
$body = @{
|
||
source = "athena"
|
||
source_type = "agent"
|
||
source_name = "Athena Agent"
|
||
kind = "html_fragment"
|
||
theme = "tasks"
|
||
title = "Task List"
|
||
content = "<h1>Tasks</h1><ul><li>Review API docs</li><li>Publish next artifact</li></ul>"
|
||
tags = @("tasks")
|
||
} | ConvertTo-Json -Depth 5
|
||
|
||
Invoke-RestMethod `
|
||
-Uri "http://127.0.0.1:8001/api/artifacts" `
|
||
-Method Post `
|
||
-Headers @{ Authorization = "Bearer <your-personal-token>" } `
|
||
-ContentType "application/json" `
|
||
-Body $body
|
||
```
|
||
|
||
## 4. Publish A File
|
||
|
||
```powershell
|
||
curl.exe -X POST "http://127.0.0.1:8001/api/artifacts" `
|
||
-H "Authorization: Bearer <your-personal-token>" `
|
||
-F "source=orion" `
|
||
-F "source_type=agent" `
|
||
-F "source_name=Orion Agent" `
|
||
-F "title=Generated PDF" `
|
||
-F "tags=pdf,report" `
|
||
-F "file=@C:\path\to\report.pdf;type=application/pdf"
|
||
```
|
||
|
||
## 5. Find Recent Artifacts
|
||
|
||
> **Note:** artifact read endpoints (steps 5 and 6) require a logged-in **browser session**;
|
||
> a bearer token is not accepted. These are for browsing from the app, not for agents.
|
||
> Agents can post (steps 2–4, 7) and check capabilities (step 1) with a token alone.
|
||
|
||
```powershell
|
||
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?source=hermes-research"
|
||
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?label=status"
|
||
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts?kind=markdown&q=status"
|
||
```
|
||
|
||
## 6. Read One Artifact Metadata
|
||
|
||
```powershell
|
||
Invoke-RestMethod "http://127.0.0.1:8001/api/artifacts/$($artifact.id)"
|
||
```
|
||
|
||
## 7. Update Metadata
|
||
|
||
```powershell
|
||
$body = @{
|
||
tags = @("status", "agent", "reviewed")
|
||
metadata = @{
|
||
run_id = "run-001"
|
||
model = "gpt-5.5"
|
||
reviewed = $true
|
||
}
|
||
} | ConvertTo-Json -Depth 5
|
||
|
||
Invoke-RestMethod `
|
||
-Uri "http://127.0.0.1:8001/api/artifacts/$($artifact.id)" `
|
||
-Method Patch `
|
||
-Headers @{ Authorization = "Bearer <your-personal-token>" } `
|
||
-ContentType "application/json" `
|
||
-Body $body
|
||
```
|
||
|
||
## 8. Delete An Artifact
|
||
|
||
```powershell
|
||
Invoke-RestMethod `
|
||
-Uri "http://127.0.0.1:8001/api/artifacts/$($artifact.id)" `
|
||
-Method Delete `
|
||
-Headers @{ Authorization = "Bearer <your-personal-token>" }
|
||
```
|
||
|
||
Deletes the artifact's database row and its files. You can only delete artifacts your own token owns.
|
||
|
||
## Agent Payload Checklist
|
||
|
||
Recommended fields for every agent post:
|
||
|
||
- `source`: stable label identifying what posted this (agent-profile, script, or person name).
|
||
- `source_type`: usually `agent`.
|
||
- `source_name`: readable agent name.
|
||
- `source_id`: stable ID if the agent has one.
|
||
- `title`: useful human title.
|
||
- `kind`: artifact type.
|
||
- `content` or `file`: artifact content.
|
||
- `tags`: small set of useful filters.
|
||
- `metadata.run_id`: lets later artifacts be correlated to the same agent run.
|
||
- `metadata.model`: model or system that generated the artifact.
|