Skip to content

Build one solution as a partner that you can use at several customer organisations

At the end of this tutorial the support assistant you built once is a publication in your own organisation, and it is installed at Noordwind with Noordwind's company name, model and ticket system. You have rolled out a new version and know what happens when a customer detaches a member.
Building blocks Sharing and reuse: publication, version, subscription, copy. Organisations and customers, Agents
You need an account with which you administer your own organisation in the console; in your own organisation the agent support and the toolset support, and a key with agents for step 2; a customer organisation under yours (Noordwind), holding an API connector to its ticket system with that host allowed (step 5); for the check, the secret of Noordwind's key Support portal and a key of your own organisation with management
Builds on Build an agent that combines knowledge and tools for the agent and the toolset, and Set up a new customer organisation for Noordwind. With only the agent from the first tutorial you can follow the tutorial too: leave tools out of the body of step 2 and skip the lines about the toolset. An agent that names a toolset that does not exist answers 404

This tutorial uses the console. The form for a version lets you choose per member what an installer fills in, and Check shows beforehand what an installation means. The same actions exist as routes (Publish and install through the API).

1. Decide what goes in the bundle

A publication puts copies in the customer's organisation. So decide per part first whether it is the same for every customer.

Part The same for every customer? Choice
the agent support yes, apart from the company name and the model in the bundle; the installer fills in name and model
the toolset support yes in the bundle
the API connector to the ticket system no, every customer has a system of its own not in the bundle; the installer chooses its own connector
the handbook no, every customer has a handbook of its own not in the bundle; the customer makes its own search tool handbook

The handbook stays out for a reason you need to know. When you put a collection in a bundle, Core fills the copy at the customer with the documents from your collection. As long as the copy is linked, the customer cannot put anything in it itself; that is possible only after the customer has detached the collection, and it then no longer follows your documents. That fits documentation that is the same for all your customers, such as the manual of your own product, and not one customer's handbook.

What cannot go in a publication: a knowledge graph, a datastore, memory, a schedule, a key and an organisation's policy. A bundle can recommend a key policy; Core never applies it itself.

2. Make the agent independent of one customer

The agent's instruction names Noordwind. Replace the name with an install value. This is a new version of the agent in your own organisation:

curl -s -X POST "$CORE_URL/agents/$AGENT_ID/versions" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"model": "<a model id>",
         "instructions": "You are the support assistant of {{ $company }}. Answer briefly.\n\n1. For every question, search the handbook first and refer to the passage with [n].\n2. If the handbook solves the question, do not create a ticket.\n3. If the handbook does not solve the question, or the customer asks for a ticket, create one.\n4. Name the ticket number and say what the customer can expect.",
         "install_values": {"company": "our company"},
         "temperature": 0.2,
         "max_tool_rounds": 4,
         "tools": [{"type": "toolset", "name": "support"}]}'

{{ $company }} is an install value: text that belongs to the organisation and that Core fills in before the instruction goes to the model. Your own value, here our company, becomes the default for every installer. So choose something neutral: a customer who leaves the field empty gets your value.

In the console the same field is Install values under an agent's instructions (Text the installer fills in).

3. Create the publication

  1. In your own organisation open Publications and choose New publication.
  2. Enter support-assistant under Name and write a description. Subscribers see both.
  3. Under Who may see this choose Organisations below.
  4. Switch on Install automatically in new organisations.
  5. Choose Create publication.

Organisations below makes the bundle visible to every organisation under yours and to nobody else. With automatic installation every organisation you create from now on subscribes straight away. The publication shares nothing yet: only a version does that.

4. Publish a version

Choose Publish a new version and walk through the form:

  1. What goes in. Open Agents and tick support. Open Toolsets and tick support.
  2. Let the installer choose. Under the agent switch on the field model. Under the toolset switch on Let the installer choose an API connector at api__create_ticket.
  3. Parameters. There are now three parameters: company (marked From your own install values), one for the model and one of type API connector. Give the last one the name ticket_system, switch on Required and write under Explanation shown at install what you expect, for example "The API connector that creates a ticket in your ticket system".
  4. Terms. Leave Detach and change on.
  5. What changed. Write "First version".
  6. Choose Publish version.

Why these choices:

  • The model as a parameter lets a customer choose a model that is available in its organisation. Your current model is the default.
  • The API connector as a parameter makes the toolset point at each customer's own ticket system. The connector itself, with the address and the token, does not leave your organisation.
  • The pattern knowledge__handbook in the toolset travels unchanged. At the customer it matches the customer's own search tool of that name, once that exists. A pattern that matches nothing offers nothing and gives no error.
  • Allowing detach gives a customer the option to take a member over and change it. Switch it off and every copy stays equal to your version.

5. Install at Noordwind

Noordwind existed before you made the publication, so automatic installation did not apply to it. You install by hand.

  1. Open Noordwind from Organisations.
  2. When Noordwind has no API connector to its ticket system yet, add it first under API connectors and allow the host, as in Let an agent carry out an action with a tool.
  3. Open Installed, go to Available and click support-assistant.
  4. Under What you fill in enter: Noordwind for company, a model of Noordwind for the model, and the connector from step 2 for ticket_system.
  5. Choose Check. The report names the functions the bundle needs that are not on, names that are already taken and, per key, what its policy would refuse.
  6. Tick I accept the terms of this publication. and choose Install.

The subscription is first Installing and then Linked. Only a missing capability blocks an installation; the rest of the report is advice.

6. Look at what Noordwind received

In Noordwind open Agents. The agent support is there, with Shared through support-assistant beside it. Under Toolsets the toolset support is there in the same way.

  • They are copies, and they are Noordwind's: they fall under the policy of its keys and their usage is booked to Noordwind.
  • The instruction in the copy holds Noordwind literally where {{ $company }} stood.
  • As long as a copy is linked, Noordwind cannot change it. That is how you know every customer runs what you published.

The agent searches a handbook only once Noordwind has a search tool with the identifier handbook. The customer makes it, or you make it for the customer, with one of Noordwind's keys as in Give an agent knowledge from your own business information. The toolset then takes it in by itself.

Check that it works

Call the agent with Noordwind's key from the previous tutorial:

curl -s -X POST "$CORE_URL/responses" \
    -H "Authorization: Bearer <the secret of Support portal>" -H "Content-Type: application/json" \
    -d '{"agent": {"id": "support"}, "input": "Which company do you work for?"}'

The answer names Noordwind. At the end of the previous tutorial the same call still answered 404.

With a key of your own organisation that has management you read the state of the installation without the console:

curl -s "$CORE_URL/organisations/ten_9Fb2.../subscriptions" -H "Authorization: Bearer $CORE_KEY"

{
  "items": [
    { "id": "sub_1Ac7...", "publication_name": "support-assistant", "status": "linked",
      "installed_version": 1, "follow": "latest",
      "config": { "company": "Noordwind", "ticket_system": "tool_8Yp3..." } }
  ]
}

The answer is abridged; config also holds the chosen model.

7. Roll out an improvement

You want the agent to ask for the order number with every ticket. In your own organisation make a new version of the agent, as in step 2, with that sentence in the instruction. Then choose Publish a new version on the publication again, with the same members and choices, and write under What changed what a customer needs to know.

Every subscription that follows the latest version gets the new version by itself: Core syncs the copies. At Noordwind installed_version is then 2. So a new version of the agent in your own organisation reaches a customer only when you bring out a version of the publication. That gives you room to test first.

A customer who does not want to follow every version chooses, when installing, under Advanced at New versions to stay on the version it installs. When a subscription becomes Stuck, the reason is on the subscription's page; after fixing it you choose Sync now.

8. Let a customer detach a member

Noordwind wants a tone of its own in the instruction. Open the subscription under Installed and choose Detach at the agent support.

After detaching, the agent is Noordwind's: its administrators can change it, and it follows no new versions any more. The subscription is Partly detached; the toolset stays linked and does follow. Detaching cannot be undone. So agree with a customer who maintains the agent afterwards, because your improvements no longer reach it.

A next customer

Create a new organisation as in the previous tutorial. The publication is installed there automatically, and the subscription is Needs configuration: the parameter ticket_system is required and has no default. Add that customer's API connector, open the subscription, fill in the connector, the company name and the model under Configuration and choose Save configuration. After that the bundle is installed.

If it does not work

You see Cause Fix
the publication is not under Available there is no version yet, or the organisation does not sit under yours publish a version; check the tree on Organisations
Core refuses the version a parameter a member uses is not required and has no default switch on Required or fill in a Default value
Check reports a function that is not on the bundle uses a capability outside the customer's ceiling switch the capability on in the customer's Permitted capabilities, and in every organisation above it
the subscription is Needs configuration a required value is missing fill it in under Configuration and choose Save configuration
the subscription is Stuck the last sync failed, for example because the chosen connector was deleted read the reason, fix the cause and choose Sync now
the agent says our company the installer left company empty, so your default applies fill in the name under Configuration of the subscription
404 when the customer's key calls the agent that key's policy does not allow the agent's name, for example because of a prefix at install change the rule over Agents, or install without a prefix

Read on

This is the last tutorial. The Core model shows how the building blocks you have used fit together.