Quickstart for agents

You are an agent acting for a human on AgentGrid.io.

Read the current contract

Start with:

https://api.agentgrid.io/connect

Follow that source for current connection mechanics and error meanings. Human approval may be required; relay the approval step and pause.

Discover scope before acting

After connection, list reachable workspaces and their capabilities. A reachable workspace is one the agent has permission to access. A capability allows an action such as reading or writing. With CLI 0.9, anima workspaces provides workspace IDs. anima list spans reachable workspaces, while anima list --workspace <id> filters to one.

Never assume connection grants the entire team. Workspace access and capabilities are separate.

Create in the requested workspace

Use the human-selected workspace. anima create --workspace <id> supports an explicit destination. The option may be omitted only when the agent can create in exactly one workspace; otherwise there is no default.

Return the artifact URL, then verify the artifact can be listed or opened in that workspace. Connected work requires no claim and does not expire.

Work safely

• Keep revisions on the same artifact unless the human requests a copy.
• Never publish without an explicit request.
• Do not imply a human-only team, workspace, or stewardship decision was completed.
• A workspace denial, revocation, or quota refusal cannot be fixed by repeating the same request. Explain the refusal without revealing hidden details.
• Repeating creation or duplication can create another artifact. After a timeout, list recent artifacts before retrying.

Unconnected fallback

If no supported connection is possible, anonymous creation may return a claim link. State before creating that it is read-only, ownerless, and expires 24 hours after creation unless claimed. See What is claiming.

Related pages

• Workspace access
• The Anima CLI
• What your agent can and cannot do

Questions and answers

What must I know before creating anything? Confirm the requested task, the destination workspace, and that the agent has the required capability there.

When may I omit --workspace? Only when the agent can create in exactly one workspace. If several are writable, there is no default.

How do I verify creation? Return the artifact URL, then list or open the artifact in the selected workspace.

Should I retry a workspace or quota denial? No. Ask the human to resolve access or plan state. After a create timeout, list recent artifacts before deciding whether to retry.

Preconditions

• Read https://api.agentgrid.io/connect.
• Obtain human approval when requested.
• Confirm the intended task and destination workspace.
• Confirm the required capability, meaning permission for the requested action, is available in that workspace.

Discover and select

With CLI 0.9:

anima workspaces
anima list --workspace <id>

anima workspaces returns reachable workspaces and capabilities. A reachable workspace is one the agent identity has permission to access. anima list without --workspace spans all reachable workspaces. Never infer access to other team workspaces.

Create

Use:

anima create --workspace <id>

The workspace option is optional only when create access exists in exactly one workspace. When several destinations are writable, no default exists and the ID is required. After creation, list or open the returned artifact to verify its workspace and URL.

Constraints

Authorization requires the team role and workspace grant plus the agent capability and steward's live permission. Connected work is owned and does not expire. An agent uses no team seat.

Never publish unless the human explicitly requests it. Do not perform or claim human-only membership, access, or stewardship decisions.

Failure handling

Anonymous fallback

Only when connection is unavailable: an anonymous artifact is read-only, ownerless, and expires 24 hours after creation unless claimed. Disclose those conditions before creating it.

Questions and answers

Where does the current connection contract come from? Read https://api.agentgrid.io/connect before acting and pause for any required human approval.

Which workspace identifier is valid? Use an ID returned by reachable-workspace discovery. Do not guess from the team or artifact URL.

What result must creation return and verify? Return the artifact URL, then list or open it to confirm the requested workspace.

When is anonymous creation acceptable? Only when supported connection is unavailable, after disclosing that the artifact is read-only, ownerless, and expires after 24 hours unless claimed.