Skip to main content

Shortcut System Guide

Shortcuts are the fastest way to invoke FAOS agents. Instead of looking up agent IDs and constructing API calls, use a simple two-part command.

How Shortcuts Work​

A shortcut command follows the pattern:

<module> <agent>
PartDescriptionExample
ModuleIndustry verticalbank, health, mfg
AgentSpecialist within modulecredit-analyst, patient-intake

When you call client.shortcut("bank credit-analyst"), the SDK:

  1. Sends the command to the shortcut resolution API
  2. Matches against registered shortcut patterns
  3. Returns the resolved agent ID and metadata
  4. Invokes the matched agent

Available Modules​

FAOS includes 21 industry modules:

ShortcutModuleAgents
bankBanking & Finance38
investInvestment Management25+
insuranceInsurance25+
fintechFinTech25+
healthHealthcare30+
mfgManufacturing25+
retailRetail20+
logisticsLogistics & Supply Chain25+
talentTalent & HR20+
profservProfessional Services25+
martechMarTech20+
softwareSoftware Development25+
siSystems Integration20+
autoAutomotive25+
aviationAviation20+
agriAgriculture20+
agritechAgriTech20+
travelTravel & Hospitality20+
gameGaming20+
edutechEduTech20+
proptechPropTech20+

Shortcut Types​

Module Shortcuts​

View all agents in a module:

# Python
shortcuts = await client.shortcuts.list(module="faos-bank")
// TypeScript
const shortcuts = await client.shortcuts.list({ module: 'faos-bank' });

Agent Shortcuts​

Invoke a specific agent directly:

# Python
response = await client.shortcut("bank credit-analyst")
// TypeScript
const response = await client.shortcut('bank credit-analyst');

Fuzzy Matching​

If you mistype a shortcut, the resolution API returns suggestions:

from faos import ShortcutNotFoundError

try:
    await client.shortcut("bnk credit-analyst")
except ShortcutNotFoundError as e:
    print(e.suggestions)
    # ["bank credit-analyst"]

Resolution Details​

When resolving a shortcut, you get full context about the matched agent:

resolution = await client.shortcuts.resolve("bank credit-analyst")

print(resolution.resolved)       # True
print(resolution.agent_id)       # "agent_abc123"
print(resolution.module_key)     # "faos-bank"
print(resolution.module_name)    # "Banking & Finance"
print(resolution.agent_name)     # "Credit Risk Analyst"
print(resolution.task_template)  # Default task for the agent
print(resolution.capabilities)   # ["credit_analysis", "risk_assessment"]

Using Context Hints​

Provide context to help resolve ambiguous shortcuts:

resolution = await client.shortcuts.resolve(
    "analyst",
    context={"industry": "banking", "task": "credit risk"}
)

Task Override​

Override the default task template when invoking via shortcut:

response = await client.shortcut(
    "bank credit-analyst",
    task="Analyze credit risk for a $500K commercial loan application"
)

Searching Shortcuts​

Search across all modules for agents matching a keyword:

results = await client.shortcuts.list(search="risk")
for s in results:
    print(f"{s.pattern}: {s.description}")
# bank risk-manager: Portfolio-level risk assessment
# insurance risk-assessor: Insurance risk evaluation
# invest risk-analyst: Investment risk analysis

Best Practices​

  1. Use specific shortcuts -- "bank credit-analyst" is better than "analyst"
  2. Cache resolutions -- If calling the same shortcut repeatedly, resolve once and reuse the agent ID
  3. Handle not-found gracefully -- Always catch ShortcutNotFoundError and show suggestions to users
  4. Stream for long responses -- Use shortcut_stream() for agent tasks that produce lengthy output

Next Steps​