Agent & portals

The agent section is written after the station and its tests; only its evals follow it. It describes the agent Convoy deploys for this station. This agent is a client of the station like any other: it goes through the same tools, the same guards, the same decision point as Claude, ChatGPT or a company's agent.

agent:
  name: Teranga
  persona: "a warm host who helps put the meal together"
  tone: friendly
  rules:
    - "Offer a drink once the meal is chosen."
  emoji: false                           # a discreet emoji in replies, or none
  model: gemini-2.5-flash                # the model the agent runs on
  mode: assisted                         # assisted | autonomous — what `agent.mode` reads in submitted_by
  portals:
    web:
      widget:
        origins: [https://teranga.example.sn]   # the only sites where the widget loads
        theme: {primary: "#1B7A4B", secondary: "#F4E9D8", font: manrope}   # the widget's colours and typeface
        identity: {auth: anonymous}
      pwa: {name: "Teranga & Me"}
    whatsapp:
      number: "+221 77 000 00 00"
      identity: {auth: telephone}
    teams: {app: teranga-pro, identity: {auth: salaries}}
    slack: {workspace: teranga, channel: "#commandes", identity: {auth: salaries}}

What belongs to the agent, and what belongs to the station

to the agent (agent)	to the station
its voice: name, persona, tone	what is permitted: guards, profiles, policies, budgets
its behaviour instructions (rules)	what every agent must respect
its portals, their theme, their welcome text	the tools, the journeys, the submit
how each portal proves who is speaking	what is done with that identity (the profiles)

An instruction is not a rule

"Never give binding legal advice" must hold for Claude too. So it is not an instruction for our agent: it is a policy of the station (effect: rewrite on the output). In agent.rules, put only what concerns the way of speaking and helping.

Portals

portal	for whom	typical identity
web.widget	visitors to the tenant's site	anonymous, or an assertion provider if the site signs in its customers
web.pwa	the person's room, installable on their phone	the room's
whatsapp	customers who write to the tenant's number	an otp provider on the phone
teams, slack	an organisation's employees	an oidc provider: Okta, Auth0, Keycloak, Entra ID (the directory gives roles and teams)

identity.auth names the identity provider the portal offers, or anonymous. The agent then acts for this person: their profiles, their rights, their budgets. An anonymous widget visitor has the anonyme profile; a manager in Teams has their roles from the directory.

origins names the only sites the widget loads on: without it, the widget would load on any site, with the tenant's brand and room.

Identity providers

identity.auth names a provider that the station declares in station.identity.providers: a code by SMS or e-mail (otp), an SSO (oidc), the tenant's login (assertion). They are described, with the difference between an identified room and an authenticated person, in Identity. When a skill requires a proof, the portal shows its provider's flow: see Asking for authentication.

Portals are not inboxes

An inbox (inboxes) is where the station asks a person to decide. A portal is where our agent speaks. A manager approves in Teams whether or not the station's agent is deployed there: the two are configured separately.

The MCP door

It belongs to the station, not to the agent: it is through it that other people's agents connect. It always exists. Without an agent section, the station can only be reached that way.