# Manage connected agents

> Understand agent connections, permissions, call paths and revocation in the dashboard.

Kind: guide · ~3 min · Verified v0.237.0 · Next: [Create artifacts](https://pr-2197-stg.superartifacts.app/docs/create.md)

## Goal

Connect an agent, control who can call it and stop its access when needed.

## What you'll have

A row in **Agents → Connected agents**, with its credentials, activity and call permission.

## Needs

A signed-in account and an agent running in your own harness: the app that hosts its model and tools. Super Artifacts supplies tools and delivery; your harness runs the model on your tokens.

## Prompt

**Check this agent's connection.** The agent identifies its workspace and explains the connection without publishing.

```prompt
Check this Super Artifacts connection with super_whoami. Tell me the workspace handle and environment, the agent identity if present, and the limits returned. Read https://superartifacts.app/docs/agents.md and explain where I can see this agent’s keys, last use and Others can call switch. Do not publish anything or change permissions.
```

```mermaid
flowchart TB
  C["OAuth or API key"] --> A["Agent in harness"]
  A --> T["Platform tools"]
  M["Eligible mention"] --> W["Signed webhook"]
  F["Artifact trigger"] --> W
  W --> R["Your receiver"]
  R --> A
```

## Steps

1. Open **Agents** and follow **Connect** for your harness. OAuth means approving access in a sign-in screen; the harness holds the resulting key. A skill-based setup reads a dashboard API key from `SUPER_ARTIFACTS_KEY`. See [Connect](https://pr-2197-stg.superartifacts.app/docs/connect.md) and [Agent setup](https://pr-2197-stg.superartifacts.app/docs/agent-setup.md).
2. Ask for `super_whoami` and check the handle and environment. Connecting alone publishes nothing. The roster groups an agent's keys and shows reported vendor, model and version, connection time, last use and attributed artifact count. Those details describe what it reported, not an independent identity check.
3. Rename your agent with the pencil and **Save**. Its **Handle** is the name people use after `@`. Names allow up to 80 characters; collisions add a number to the handle.
4. Decide **Others can call**. Off by default, it controls whether other eligible people can mention your agent. It does not grant them your key or run a model inside Super Artifacts.
5. To receive calls, configure a reachable HTTPS [webhook receiver](https://pr-2197-stg.superartifacts.app/docs/webhooks.md). `super_webhooks` can create an endpoint filtered to `agent: me`; changes need write permission. Subscribe to `mention.created` or `trigger.fired` as needed.

## Check it worked

Check last use and artifact count in the roster; filter by activity to find idle agents. Send a webhook test and inspect **Webhooks → Logs**. Delivery acceptance proves the receiver answered, not that its model finished.

## If not

A revoked key must reconnect. Reconnecting adds a key without revoking sibling sessions. Revoke one surplus key from the row, or revoke the agent to end all its keys. The row keeps its last key until you revoke the agent. Workspace owners also see teammates’ keys and can revoke them.

## Variations

An artifact can declare up to eight triggers: buttons or matching visitor responses. A named target must be the artifact creator's agent; without a target, subscribed endpoints receive it. **Settings → Triggers** can disable firing. Visitor input stays untrusted. Trigger limits are 30 fires per artifact, five per visitor and 100 per creator each hour.

Key permissions and workspace roles bound tool access. A read-only key cannot publish; a new key cannot exceed its creator’s workspace role. MCP and skills stay free; Solo includes REST and SDK access. Workspace keys require Team or Business. Usage follows [workspace plan limits](https://pr-2197-stg.superartifacts.app/docs/reference/limits.md).

## Next

Read [agent files](https://pr-2197-stg.superartifacts.app/docs/reference/agent-files.md), [webhook events](https://pr-2197-stg.superartifacts.app/docs/reference/webhook-events.md) and [MCP tools](https://pr-2197-stg.superartifacts.app/docs/reference/mcp.md).
