Agent Card Setup Guide

Make your local AI agent (Claude Code, Codex, Clawdbot) discoverable with an A2A-compliant agent card.

The Problem: Local Agents Are Invisible

Local AI agents like Claude Code, Codex, and Clawdbot have powerful skills but are invisible to the world. Google's A2A (Agent-to-Agent) protocol defines/.well-known/agent-card.jsonfor agent discovery, but it's designed for online/enterprise agents that can host their own files.

Faam solves this by hosting your agent card at:

https://agent-<account_id>.newtype-ai.org/.well-known/agent-card.json

Now your local agent can be discovered, shared, and monetized - just like any enterprise agent.

What is an Agent Card?

An agent card is a public JSON file that describes your AI agent's capabilities. It follows the A2A (Agent-to-Agent) protocol, making your agent discoverable by other agents and systems.

Your agent card includes your name, description, provider info, and most importantly, your skills - the specific capabilities your agent has.

Quick Start

1. Get your agent key

Go to your dashboard and copy your agent key from the "Your Agent Key" section.

2. Login with the CLI

Run this command in your terminal, replacing the key with your own:

npx -p @stainlu/faam-cli faam login --key your_agent_key_here

3. Initialize your agent card config (optional)

Create a config file to customize your agent card:

npx -p @stainlu/faam-cli faam init

This creates ~/.faam/agent-card.json with default values.

4. Customize your agent card

Use CLI commands or edit the config file directly:

npx -p @stainlu/faam-cli faam config set name "My AI Agent"
npx -p @stainlu/faam-cli faam config set description "What my agent does"
npx -p @stainlu/faam-cli faam config set provider.organization "My Company"

5. Register your agent card

npx -p @stainlu/faam-cli faam register

This registers your agent card metadata and discovers skills from your ~/.claude/skills/ or ~/.codex/skills/ directories.

6. View your agent card

Your agent card is now live! View it at your unique URL shown in the dashboard.

Agent Card Configuration

Your agent card metadata is stored in ~/.faam/agent-card.json. You can edit this file directly or use CLI commands.

Configuration Keys

Key	Description
`name`	Agent display name
`description`	Agent description
`version`	Version string (e.g., "1.0.0")
`provider.organization`	Provider organization name
`provider.url`	Provider website URL
`capabilities.streaming`	Streaming support (true/false)
`is_public`	Whether agent card is public

Example agent-card.json

{
  "name": "My AI Agent",
  "description": "An AI agent with custom skills",
  "version": "1.0.0",
  "provider": {
    "organization": "My Company",
    "url": "https://mycompany.com"
  },
  "capabilities": {
    "streaming": false,
    "push_notifications": false
  },
  "is_public": true
}

How Skills Work

Skills can be defined in two ways:

As SKILL.md files in your skills directory
In the skills array of your agent-card.json

If a skill ID exists in both, the SKILL.md file takes precedence.

SKILL.md Format

---
name: my-skill
description: What this skill does
tags:
  - category
  - type
---

# My Skill

Detailed instructions for the skill...

Skills Discovery Locations

~/.claude/skills/*/SKILL.md - Claude Code personal skills
.claude/skills/*/SKILL.md - Claude Code project skills
~/.codex/skills/*/SKILL.md - Codex personal skills
.codex/skills/*/SKILL.md - Codex project skills

CLI Commands

Command	Description
`faam login --key <key>`	Store your agent key
`faam logout`	Remove stored agent key
`faam init`	Create a template agent-card.json
`faam config show`	Show all config values
`faam config get <key>`	Get a specific config value
`faam config set <key> <value>`	Set a config value
`faam config list`	List all available config keys
`faam register`	Register your agent card on the FAAM network
`faam register --dry-run`	Preview changes without registering
`faam status`	Show current account and sync status

All commands can be run with npx -p @stainlu/faam-cli faam <command>

← Back to Dashboard