What an agent can do
Every tool a connected agent can use, what each costs, and the rules it cannot get around.
A connected agent acts as you, on the projects you can already reach. It can't see anyone else's work, and it can't do anything the dashboard wouldn't let you do. This page lists the tools Appentic gives it, grouped by what they're for.
Looking around
These cost nothing and change nothing.
| Tool | What it does |
|---|---|
whoami | The account the agent acts as, its workspaces, your credit balance and your low-balance alert |
list_projects | Every project you can reach, with its geo and whether it has a machine yet |
get_project | A project's machines, with the memory each has guaranteed, not yet guaranteed and actually free right now. Every service with its memory and the machine it runs on, and whether each web service, worker and cron job uses idle memory. Addresses, statuses, database storage and domains. |
list_machines | The machines that can be bought in a geo right now, with memory, cores, disk and monthly price |
list_services | The kinds of service Appentic runs, what each is for, and what each costs a month |
read_guide | A guide on building here (start), the Feather framework (feather) or how an app should look (design) |
Pricing first
check_plan answers whether a machine plus a set of services fits, and what it costs a month. For a project that already has machines, it checks against one of them. Nothing is created.
Building
These cost money. Appentic refuses each one unless the agent passes an explicit confirmation, and tells it to quote the price and ask you first.
| Tool | What it does | Cost |
|---|---|---|
create_project | A new project in one of your workspaces | Nothing. A project with no machine is free. |
create_web_service | The app's web service, from an Appentic-hosted repository or your own GitHub repository. Adds the project's first machine if it has none. | The machine's price and the service's fee. From here the project bills by the second. |
add_service | A database, key value store, worker, cron job, storage, custom domain, firewall, volume or Key service | A fee per service on top of the machine. Storage also pays for what it holds, and a volume for its size. A custom domain is free. |
provision_feather_stack | Everything a Feather app needs in one call: Postgres, plus a key value store, a worker and storage if the app needs them | The same fees as adding each one |
set_database_backups | Turns a database's continuous backups on or off | The backup fee while they're on |
Appentic refuses a billable call without the confirmation and tells the agent to ask you. Your agent's own permission prompt is where you see each call and say yes. Check the price it quotes before you approve.
A new service goes on the web service's machine unless the agent names another of the project's machines.
A machine is billed from the moment it's ready, whether or not anything is deployed on it. If an agent creates a project you don't want, delete it. See Deleting a project.
Sizing
| Tool | What it does | Cost |
|---|---|---|
set_memory | Changes the guaranteed memory of a web service, worker, cron job, database or key value store. For a web service, worker or cron job, it also sets whether it can use idle memory. | Nothing. Memory doesn't change the price. |
set_memory is how an agent makes room on a machine without a bigger machine. The change applies at once. A web service restarts, a worker redeploys, and a database or store resizes and is briefly offline.
Removing
remove_services removes a worker, key value store or cron job for good. It first says what would go, and acts only when the agent calls again with a confirmation after asking you. A key value store a worker reads from goes only with that worker.
A database, storage or volume holds your data, so an agent can't remove one. Neither can it remove a Key service, whose key opens your data. Delete those on the dashboard.
The Key service
| Tool | What it does |
|---|---|
kms_status | The project's Key service: its state, key version, the variables your app reads, and its latest calls |
rotate_kms_key | Adds a new version of the key. Everything wrapped before still unwraps. |
disable_kms_key | The emergency stop. Every use of the key is refused at once and your services and workers restart without it. The agent must ask you first. |
enable_kms_key | Undoes the emergency stop |
Shipping
| Tool | What it does |
|---|---|
get_repository | A push address for an Appentic-hosted repository, with a credential for that one repository that lasts an hour. For your own repository, its name and branch. |
deploy | Builds and releases what was pushed. Returns straight away with a deployment id. |
get_deployment | A deploy's status, commit and build output, and the exact version of every package the build installed. Waits up to two minutes at a time for the deploy to finish. |
A web service that deploys your own GitHub repository also deploys when you push, as usual.
Troubleshooting
| Tool | What it does |
|---|---|
app_health | Whether the app works, not only whether it runs. Its home page must not error, and its health check, if it has one, must pass. After a deploy, restart or new variable it can wait up to two minutes for the app to settle. A crashing service says why. It also lists every worker, and a crashing worker shows up with why. |
get_logs | The most recent lines the running app printed |
read_code | A file or a folder listing from the web service's repository, at the commit that's deployed |
restart_service | Starts a web service or a worker again as it is, without a rebuild, for one that's stuck |
push_fix | Pushes a fix to your own GitHub repository, as a commit on the branch the web service deploys, which deploys it. For an agent that doesn't have the repository checked out. |
get_fix | Follows the deploy of a pushed fix, and starts it if nothing else did |
push_fix works only once you allow it, on the same terms as Athena's fixes. The web service needs Code fixes turned on in its Settings, and Appentic's GitHub App needs your approval on GitHub to change code. A protected branch gets a pull request instead. See Pushing a fix to your code.
Settings and the machine
| Tool | What it does |
|---|---|
list_env_vars | The project's variable names, when each was set, and whether the app has run with it yet. Never the values. |
set_env_var | Sets or replaces one variable. The value can't be read back. A running app restarts with it within a few seconds, without a rebuild. |
run_on_machine | Runs one command on the project's machine, beside its database and services, with the app's requirements installed and a throwaway database for tests |
run_on_machine is for migrations and for tests that need the real services. It works only for an app on a repository Appentic created for the project, runs the latest pushed code (so the agent pushes first), and needs 128 MB not yet guaranteed on the machine, plus enough memory free right now for the command. When there isn't room, it says what to change. It runs against your real database, so a migration run there is applied for real.
What you add on the dashboard
An agent buys a project's first machine and adds services to the machines the project has. These are yours to add on the dashboard:
- more machines, on the project's Resources page. See Machines.
- a second web service
- load balancers across web services
- standbys for a database or key value store
An agent asked for one of these tells you to add it on the dashboard. Agents also can't delete projects, web services or anything that holds data, change a machine's size, roll back a deploy or restore a backup. Do those on the dashboard too.
What it cannot do
- Read your secrets. Variable values are encrypted and never returned, to an agent or to anyone else.
- Touch another account. A connection reaches only the workspaces you belong to.
- Push to your code without your permission.
push_fixneeds Code fixes on for that repository and your approval on GitHub. - Get outside your project. Commands run inside your project, with the same limits as your app.
- Outlast being disconnected. Disconnecting it under User settings → Connected accounts stops it straight away.
What it reads before it starts
The server carries its own guides, so you don't have to explain Appentic to your agent. "Read the start guide first" is a good opening line: an agent that has read it knows to quote before it adds anything, and that uploads belong in storage rather than on the container's disk.
Things worth telling your agent
- Price the plan before adding anything, and show me the quote.
- Ask me which geo before you add a machine. Left alone, it uses EU-1.
- Size services to fit the machine: memory runs out first.
- Anything written inside a running container is lost on the next deploy. Files that must last go in storage. See Storage.