Custom Objects

Overview

Custom objects let you give your agents typed, app-defined data structures. Instead of asking an agent to remember "we have leads with these fields" in its prompt, you define the shape once as a schema and then create as many instances of that shape as you need.

Use custom objects when:

• the agent needs to track entities specific to your business (a lead, a release, a customer account, an incident)
• different runs need to read or update the same record over time
• you want a queryable list of those entities, not free-form notes scattered across threads

A custom object is a row of structured data. The schema describes the shape. The instances are the data the agent actually works with.

---

Schemas first

Each custom object belongs to a schema, identified by a lookup_key. The schema is a config: you define it once, ship it through the same deploy configs workflow as the rest of your project, and reference it from the agent's tools or scripts.

A schema declares:

• the fields the object has (name, type, required-or-not)
• which fields are searchable
• any defaults

See Configs for the deploy/sync flow. The kind for these schemas is CustomObjectSchema, discoverable via archagent list configkinds.

---

Create, read, update, delete

The CLI exposes a full CRUD surface keyed by the schema:

# List instances of a schema, optionally searching
archagent list custom-objects --schema-key lead
archagent list custom-objects --schema-key lead --search "acme"

# Inspect one
archagent describe custom-object <custom_object_id>

# Create a new instance with a fields payload
archagent create custom-object \
 --schema-key lead \
 --fields '{"company":"Acme","stage":"qualified","owner":"alice@company.com"}'

# Update some fields
archagent update custom-object <id> \
 --fields '{"stage":"contracted"}'

# Delete
archagent delete custom-object <id>

Pagination follows the same pattern as the rest of the CLI: --page, --page-size, and --all for scripts.

---

Owners and scoping

Custom objects can be scoped to a specific user or team:

• --user <id>: the object is owned by one user; only that user (and admins) can manage it
• --team <id>: the object is owned by a team; team members can manage it
• neither: the object is app-scoped; anyone with app access can manage it

This matters when the same schema represents both per-user state ("my drafts") and shared state ("our leads"). Pick the owner at create time and the platform enforces access automatically.

---

How agents work with them

Custom objects show up to agents through two surfaces:

• As a builtin tool. The task_list builtin and similar custom-object tools let an agent list, read, create, and update objects on a schema during an LLM session. Attach the relevant tool to the agent and reference the schema by lookup_key.
• From scripts. Scripts can read or write objects directly, useful when the logic is deterministic and you do not need the LLM in the loop. See the agents.* and namespace bindings in Scripts.

Either way, the schema is the source of truth for the shape. Agents and scripts trust it, and a misshapen update is rejected before it ever lands.

---

A practical pattern

A pipeline-tracking agent uses a lead schema with a few fields (company, stage, owner, last_touched_at). The agent's routines:

1. Read the current pipeline at the start of each session with list custom-objects --schema-key lead.
2. Update the right record when something changes, one field at a time.
3. Surface a digest in the channel the team watches.

Compared with keeping that state in conversational memory, custom objects make the data inspectable, queryable, and durable across handoffs.

---

Where to go next

1. Configs: to deploy and version-control the schemas that drive your custom objects.
2. Tools: for the builtin and custom tool path that exposes objects to an agent in an LLM session.
3. Key-Value Storage: for small structural state that doesn't warrant a schema.