Skip to main content
POST
Create A2A agent

Restrictions

Usage

  • instructions is required: a Markdown document with optional summary frontmatter and a non-empty body, at most 51,200 bytes. The deprecated description field is still accepted; if both are sent they must match exactly.
  • agent_name must not contain @ or be general / explore (reserved by built-in agents), and must be unique within its scope (account-wide or one team); violations return InvalidParameter.
  • card_url must be an absolute http/https URL with a host. When an execution environment for the agent is online, the server fetches the agent card through it (a card_url with no path gets /.well-known/agent-card.json appended) and rejects a card that is not valid JSON or declares no A2A 1.x interface with protocol binding JSONRPC or HTTP+JSON; an unreachable card, a non-2xx response, or no online environment does not block the call.
  • auth_type=bearer sends auth_config.token as Authorization: Bearer <token>; auth_type=api_key sends auth_config.api_key in the header named by auth_config.header; with none or an empty value no shared credential header is sent.
  • Each environments entry must be cloud or the ID of a BYOC runner that is account-scoped or belongs to one of the caller’s teams; duplicates are dropped and an empty string is rejected. Omitted or empty means all environments.
  • Creating into a team (team_id > 0) requires the caller to belong to that team; only the account owner or an admin may create at account scope (team_id=0).
  • A new agent starts with status=enabled.
  • Every call is recorded in the account audit log.

Authorizations

app_key
string
query
required

APP Key created in the Flashduty console under My → APP Key. Send it as the app_key query parameter or in the Fd-App-Key request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret.

Body

application/json

Registration parameters for a new A2A agent.

agent_name
string
required

Agent display name, used to address the agent in sessions. Must not contain @, must not be general or explore, and must be unique within its scope (account-wide or one team).

Maximum string length: 128
instructions
string
required

Natural-language instructions for the remote agent: a Markdown document with optional summary frontmatter and a non-empty body, at most 50 KiB (51200 bytes). Required — a deprecated description field is still accepted for legacy clients and, if both are sent, must exactly match instructions.

Maximum string length: 51200
card_url
string
required

URL of the remote agent card. Must be an absolute http or https URL with a non-empty host; a URL with no path is resolved to /.well-known/agent-card.json. If an execution environment is online, the card is fetched and must declare an A2A 1.x JSONRPC or HTTP+JSON interface.

auth_type
enum<string>

Authentication used to reach the remote agent with a shared credential:

  • none: no credential header.
  • api_key: sends auth_config.api_key in the header named by auth_config.header.
  • bearer: sends Authorization: Bearer <auth_config.token>.

When omitted the value is stored as an empty string, which behaves like none.

Available options:
none,
api_key,
bearer
auth_config
object

Shared credential key-values: header and api_key for auth_type=api_key, token for auth_type=bearer. Values of api_key, token, and client_secret are encrypted at rest and masked in responses.

streaming
boolean

Whether the remote agent supports streaming.

team_id
integer<int64>

Team scope: 0 = account-wide; >0 = team. Creating at account scope requires the owner/admin role; creating into a team requires actual membership in that team.

environments
string[]

Execution environments this agent is callable from: cloud and/or BYOC runner environment IDs. Omitted or empty means all environments.

auth_mode
enum<string>
default:shared

Who supplies the credential:

  • shared (default; an empty value behaves the same): one credential stored on the agent (auth_type + auth_config) is used for every caller.
  • per_user_secret: each user stores their own secret, sent in the header named by secret_schema.header_name.
  • per_user_oauth: each user completes their own OAuth authorization; discovery and client registration run on first use.

per_user_secret requires secret_schema with a non-empty header_name; any other value returns InvalidParameter.

Available options:
shared,
per_user_secret,
per_user_oauth
secret_schema
string

JSON-encoded secret schema, e.g. {"header_name":"X-Api-Key"}; required when auth_mode=per_user_secret.

oauth_metadata
string

JSON-encoded OAuth metadata; populated by the OAuth discovery flow for per_user_oauth mode.

allow_insecure_oauth_http
boolean

Allow non-loopback HTTP OAuth discovery/metadata endpoints for this agent instead of requiring HTTPS. Defaults to false.

allow_insecure_tls_skip_verify
boolean

Skip TLS certificate verification when connecting to this agent's endpoint (self-signed/private certs). Defaults to false.

Response

Success

Standard response envelope used by every Flashduty public API. On success data contains the endpoint-specific payload and error is absent. On failure error is present and data is absent. request_id is always present and is also mirrored in the Flashcat-Request-Id response header.

request_id
string
required

Unique ID for this request. Mirrored in the Flashcat-Request-Id header. Include it when reporting issues.

Example:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

error
object

Error payload inside the response envelope. Present only on non-2xx responses.

data
object

Result of registering an A2A agent.