The Azure AI Agent Service announced General Availability during Microsoft Build in May. This introduces a compelling AI offering for organisations to leverage within Azure. The AI Agent Service enables you to design and orchestrate multi-agent workflows, modularity, and task delegation for specific tasks.
The really cool thing about the AI Agent Service is that you can natively integrate actions into an AI agent. These actions can trigger an Azure Function, Azure Logic App, code interpretation, or an OpenAPI specification. The OpenAPI specification is the most intriguing option to me – what if I just want to chuck an OpenAPI spec at an agent and let it determine the context of my prompt and call the appropriate operation? That would be pretty epic and reliable from a data perspective as well.
In this blog, I’ll detail a use case that I think is really cool and may resonate as a scenario others will want to explore: calling the UK Companies House Public API from an Azure AI Agent in Azure AI Foundry!
Companies House
The Companies House API is a publicly available API that digitally stores a public register of UK companies. It’s free to use. We need to sign up to the service in order to get an API key for our calls in the AI Agent Service tool.
Get started with the Companies House API
Once registered, we need to create a ‘Live App’. If you create a test app, the calls will not work. This application is what will generate the API key that we will use in our AI Agent OpenAPI spec calls:
Create your agent
Prerequisites
- Azure AI Foundry resource (Cognitive Account AIService kind – or you’ll be stuck with hub based project in ‘preview’ for agents)
- Azure AI Foundry Project (created in the Cognitive Account “Azure AI Foundry” resource)
If you’re deploying via Bicep with Azure Verified Modules, these are the main parameters you’ll want to define: kind: 'AIServices' and allowProjectManagement: true. You can also deploy the models you want in the project here as well:
Create your agent
Firstly, we need to create an agent within the Foundry project. This is very simple to do. Go to your Azure AI Foundry project portal, select Agents from the left navigation pane, and you will be presented with an introductory splash screen to deploy a model if you did not deploy one using Bicep as described above. I am using gpt 4.1 mini as it is quite cost effective in terms of input and output token usage, but you can select whichever model you prefer.
Once that is done, you will be able to click Create Agent in the project to get started.
Create a project connection
The project connection is what we will use to tell the agent which authentication connection to use when it makes the OpenAPI action to Companies House. Foundry Connections are where you can store API keys, custom configurations, or connect to external data sources.
Convert your live application API key to a Base64 string using this one line PowerShell command in a pwsh terminal:
[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("API_KEY"))In your Foundry project, scroll down to the bottom left and you should see a ‘Management Center’ button which will take you to a page like below, here you can click ‘New connection’:
Scroll down and find ‘Custom keys’ under ‘Other resource types’:
Then we need to put ‘Authorization’ in the Custom key with a value of ‘Basic’ followed by the Base64 API key string created earlier on (tick is secret) and ‘Add connection’ to finish:
Adding the Companies House API tool to the Foundry Agent
The AI Agent Service requires the OpenAPI specification to be version 3 schema compliant. However, I found the Companies House specification to be invalid and had to modify it so that it could be imported correctly for use in Foundry. This included updating the security schemas and generally making the specification version 3 schema compliant. To save others the trouble, I have uploaded the corrected version to a GitHub Gist. You can copy it and use it to create an action in the Foundry AI Agent:
| { | |
| "openapi": "3.0.1", | |
| "info": { | |
| "version": "1.0.0", | |
| "title": "Companies House Public Data API", | |
| "description": "An API suite providing read only access to search and retrieve public company data", | |
| "contact": { | |
| "name": "Companies House API Support", | |
| "url": "https://developer.company-information.service.gov.uk/", | |
| "email": "[email protected]" | |
| } | |
| }, | |
| "servers": [ | |
| { | |
| "url": "https://api.company-information.service.gov.uk" | |
| } | |
| ], | |
| "tags": [ | |
| { | |
| "name": "registeredOfficeAddress", | |
| "description": "Registered office address" | |
| }, | |
| { | |
| "name": "companyProfile", | |
| "description": "Company profile" | |
| }, | |
| { | |
| "name": "search", | |
| "description": "Search" | |
| }, | |
| { | |
| "name": "officers", | |
| "description": "Officers" | |
| }, | |
| { | |
| "name": "registers", | |
| "description": "Registers" | |
| }, | |
| { | |
| "name": "charges", | |
| "description": "Charges" | |
| }, | |
| { | |
| "name": "filingHistory", | |
| "description": "Filing history" | |
| }, | |
| { | |
| "name": "insolvency", | |
| "description": "Insolvency" | |
| }, | |
| { | |
| "name": "exemptions", | |
| "description": "Exemptions" | |
| }, | |
| { | |
| "name": "officerDisqualifications", | |
| "description": "Officer disqualifications" | |
| }, | |
| { | |
| "name": "officerAppointments", | |
| "description": "Officer appointments" | |
| }, | |
| { | |
| "name": "UKEstablishments", | |
| "description": "UK Establishments" | |
| }, | |
| { | |
| "name": "personsWithSignificantControl", | |
| "description": "Persons with significant control" | |
| }, | |
| { | |
| "name": "pscDiscrepancies", | |
| "description": "PSC discrepancies" | |
| } | |
| ], | |
| "components": { | |
| "securitySchemes": { | |
| "Authorization": { | |
| "type": "apiKey", | |
| "name": "Authorization", | |
| "in": "header" | |
| } | |
| } | |
| }, | |
| "security": [ | |
| { | |
| "Authorization": [] | |
| } | |
| ], | |
| "paths": { | |
| "/company/{companyNumber}/registered-office-address": { | |
| "get": { | |
| "tags": [ | |
| "registeredOfficeAddress" | |
| ], | |
| "summary": "Get registered office address", | |
| "description": "Returns the registered office address for a company.", | |
| "operationId": "get_registered_office_address", | |
| "parameters": [ | |
| { | |
| "name": "companyNumber", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{companyNumber}": { | |
| "get": { | |
| "tags": [ | |
| "companyProfile" | |
| ], | |
| "summary": "Get company profile", | |
| "description": "Returns the company profile for a company.", | |
| "operationId": "get_company_profile", | |
| "parameters": [ | |
| { | |
| "name": "companyNumber", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/search": { | |
| "get": { | |
| "tags": [ | |
| "search" | |
| ], | |
| "summary": "Search all", | |
| "description": "Performs a search across all company data.", | |
| "operationId": "search_all", | |
| "parameters": [], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/search/companies": { | |
| "get": { | |
| "tags": [ | |
| "search" | |
| ], | |
| "summary": "Search companies", | |
| "description": "Performs a search for companies.", | |
| "operationId": "search_companies", | |
| "parameters": [], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/search/officers": { | |
| "get": { | |
| "tags": [ | |
| "search" | |
| ], | |
| "summary": "Search officers", | |
| "description": "Performs a search for officers.", | |
| "operationId": "search_officers", | |
| "parameters": [], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/search/disqualified-officers": { | |
| "get": { | |
| "tags": [ | |
| "search" | |
| ], | |
| "summary": "Search disqualified officers", | |
| "description": "Performs a search for disqualified officers.", | |
| "operationId": "search_disqualified_officers", | |
| "parameters": [], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/dissolved-search/companies": { | |
| "get": { | |
| "tags": [ | |
| "search" | |
| ], | |
| "summary": "Search dissolved companies", | |
| "description": "Performs a search for dissolved companies.", | |
| "operationId": "search_dissolved_companies", | |
| "parameters": [], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/alphabetical-search/companies": { | |
| "get": { | |
| "tags": [ | |
| "search" | |
| ], | |
| "summary": "Alphabetical search for companies", | |
| "description": "Performs an alphabetical search for companies.", | |
| "operationId": "alphabetical_search_companies", | |
| "parameters": [], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/advanced-search/companies": { | |
| "get": { | |
| "tags": [ | |
| "search" | |
| ], | |
| "summary": "Advanced search for companies", | |
| "description": "Performs an advanced search for companies.", | |
| "operationId": "advanced_search_companies", | |
| "parameters": [], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/officers": { | |
| "get": { | |
| "tags": [ | |
| "officers" | |
| ], | |
| "summary": "List company officers", | |
| "description": "Returns a list of officers for a company.", | |
| "operationId": "list_company_officers", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/appointments/{appointment_id}": { | |
| "get": { | |
| "tags": [ | |
| "officers" | |
| ], | |
| "summary": "Get company officer appointment", | |
| "description": "Returns details of a company officer appointment.", | |
| "operationId": "get_company_officer_appointment", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| }, | |
| { | |
| "name": "appointment_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/registers": { | |
| "get": { | |
| "tags": [ | |
| "registers" | |
| ], | |
| "summary": "Get company registers", | |
| "description": "Returns the registers for a company.", | |
| "operationId": "get_company_registers", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/filing-history/{transaction_id}": { | |
| "get": { | |
| "tags": [ | |
| "filingHistory" | |
| ], | |
| "summary": "Get company filing history transaction", | |
| "description": "Returns details of a specific filing history transaction for a company.", | |
| "operationId": "get_company_filing_history_transaction", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| }, | |
| { | |
| "name": "transaction_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/filing-history": { | |
| "get": { | |
| "tags": [ | |
| "filingHistory" | |
| ], | |
| "summary": "List company filing history", | |
| "description": "Returns a list of filing history transactions for a company.", | |
| "operationId": "list_company_filing_history", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/exemptions": { | |
| "get": { | |
| "tags": [ | |
| "exemptions" | |
| ], | |
| "summary": "Get company exemptions", | |
| "description": "Returns the exemptions for a company.", | |
| "operationId": "get_company_exemptions", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/disqualified-officers/natural/{officer_id}": { | |
| "get": { | |
| "tags": [ | |
| "officerDisqualifications" | |
| ], | |
| "summary": "Get natural disqualified officer", | |
| "description": "Returns details of a natural disqualified officer.", | |
| "operationId": "get_natural_disqualified_officer", | |
| "parameters": [ | |
| { | |
| "name": "officer_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/disqualified-officers/corporate/{officer_id}": { | |
| "get": { | |
| "tags": [ | |
| "officerDisqualifications" | |
| ], | |
| "summary": "Get corporate disqualified officer", | |
| "description": "Returns details of a corporate disqualified officer.", | |
| "operationId": "get_corporate_disqualified_officer", | |
| "parameters": [ | |
| { | |
| "name": "officer_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/officers/{officer_id}/appointments": { | |
| "get": { | |
| "tags": [ | |
| "officerAppointments" | |
| ], | |
| "summary": "List officer appointments", | |
| "description": "Returns a list of appointments for an officer.", | |
| "operationId": "list_officer_appointments", | |
| "parameters": [ | |
| { | |
| "name": "officer_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/charges": { | |
| "get": { | |
| "tags": [ | |
| "charges" | |
| ], | |
| "summary": "List company charges", | |
| "description": "Returns a list of charges for a company.", | |
| "operationId": "list_company_charges", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/charges/{charge_id}": { | |
| "get": { | |
| "tags": [ | |
| "charges" | |
| ], | |
| "summary": "Get company charge details", | |
| "description": "Returns details of a specific charge for a company.", | |
| "operationId": "get_company_charge_details", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| }, | |
| { | |
| "name": "charge_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/insolvency": { | |
| "get": { | |
| "tags": [ | |
| "insolvency" | |
| ], | |
| "summary": "Get company insolvency case", | |
| "description": "Returns the insolvency case for a company.", | |
| "operationId": "get_company_insolvency_case", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/uk-establishments": { | |
| "get": { | |
| "tags": [ | |
| "UKEstablishments" | |
| ], | |
| "summary": "List UK establishments for a company", | |
| "description": "Returns a list of UK establishments for a company.", | |
| "operationId": "list_company_uk_establishments", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/persons-with-significant-control": { | |
| "get": { | |
| "tags": [ | |
| "personsWithSignificantControl" | |
| ], | |
| "summary": "List persons with significant control", | |
| "description": "Returns a list of persons with significant control for a company.", | |
| "operationId": "list_company_psc", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/persons-with-significant-control/individual/{psc_id}": { | |
| "get": { | |
| "tags": [ | |
| "personsWithSignificantControl" | |
| ], | |
| "summary": "Get individual person with significant control", | |
| "description": "Returns details of an individual person with significant control for a company.", | |
| "operationId": "get_individual_psc", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| }, | |
| { | |
| "name": "psc_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/persons-with-significant-control/individual/{psc_id}/full_record": { | |
| "get": { | |
| "tags": [ | |
| "personsWithSignificantControl" | |
| ], | |
| "summary": "Get full record for individual person with significant control", | |
| "description": "Returns the full record for an individual person with significant control for a company.", | |
| "operationId": "get_individual_psc_full_record", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| }, | |
| { | |
| "name": "psc_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/persons-with-significant-control/individual/{psc_id}/verification-state": { | |
| "get": { | |
| "tags": [ | |
| "personsWithSignificantControl" | |
| ], | |
| "summary": "Get verification state for individual person with significant control", | |
| "description": "Returns the verification state for an individual person with significant control for a company.", | |
| "operationId": "get_individual_psc_verification_state", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| }, | |
| { | |
| "name": "psc_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/persons-with-significant-control/individual-beneficial-owner/{psc_id}": { | |
| "get": { | |
| "tags": [ | |
| "personsWithSignificantControl" | |
| ], | |
| "summary": "Get individual beneficial owner", | |
| "description": "Returns details of an individual beneficial owner for a company.", | |
| "operationId": "get_individual_beneficial_owner", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| }, | |
| { | |
| "name": "psc_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/persons-with-significant-control/corporate-entity/{psc_id}": { | |
| "get": { | |
| "tags": [ | |
| "personsWithSignificantControl" | |
| ], | |
| "summary": "Get corporate entity person with significant control", | |
| "description": "Returns details of a corporate entity person with significant control for a company.", | |
| "operationId": "get_corporate_entity_psc", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| }, | |
| { | |
| "name": "psc_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/persons-with-significant-control/corporate-entity-beneficial-owner/{psc_id}": { | |
| "get": { | |
| "tags": [ | |
| "personsWithSignificantControl" | |
| ], | |
| "summary": "Get corporate entity beneficial owner", | |
| "description": "Returns details of a corporate entity beneficial owner for a company.", | |
| "operationId": "get_corporate_entity_beneficial_owner", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| }, | |
| { | |
| "name": "psc_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/persons-with-significant-control/legal-person/{psc_id}": { | |
| "get": { | |
| "tags": [ | |
| "personsWithSignificantControl" | |
| ], | |
| "summary": "Get legal person with significant control", | |
| "description": "Returns details of a legal person with significant control for a company.", | |
| "operationId": "get_legal_person_psc", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| }, | |
| { | |
| "name": "psc_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/persons-with-significant-control/legal-person-beneficial-owner/{psc_id}": { | |
| "get": { | |
| "tags": [ | |
| "personsWithSignificantControl" | |
| ], | |
| "summary": "Get legal person beneficial owner", | |
| "description": "Returns details of a legal person beneficial owner for a company.", | |
| "operationId": "get_legal_person_beneficial_owner", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| }, | |
| { | |
| "name": "psc_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/persons-with-significant-control-statements": { | |
| "get": { | |
| "tags": [ | |
| "personsWithSignificantControl" | |
| ], | |
| "summary": "List persons with significant control statements", | |
| "description": "Returns a list of persons with significant control statements for a company.", | |
| "operationId": "list_company_psc_statements", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/persons-with-significant-control-statements/{statement_id}": { | |
| "get": { | |
| "tags": [ | |
| "personsWithSignificantControl" | |
| ], | |
| "summary": "Get persons with significant control statement", | |
| "description": "Returns details of a persons with significant control statement for a company.", | |
| "operationId": "get_psc_statement", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| }, | |
| { | |
| "name": "statement_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/persons-with-significant-control/super-secure/{super_secure_id}": { | |
| "get": { | |
| "tags": [ | |
| "personsWithSignificantControl" | |
| ], | |
| "summary": "Get super secure person with significant control", | |
| "description": "Returns details of a super secure person with significant control for a company.", | |
| "operationId": "get_super_secure_psc", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| }, | |
| { | |
| "name": "super_secure_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| }, | |
| "/company/{company_number}/persons-with-significant-control/super-secure-beneficial-owner/{super_secure_id}": { | |
| "get": { | |
| "tags": [ | |
| "personsWithSignificantControl" | |
| ], | |
| "summary": "Get super secure beneficial owner", | |
| "description": "Returns details of a super secure beneficial owner for a company.", | |
| "operationId": "get_super_secure_beneficial_owner", | |
| "parameters": [ | |
| { | |
| "name": "company_number", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| }, | |
| { | |
| "name": "super_secure_id", | |
| "in": "path", | |
| "required": true, | |
| "schema": { | |
| "type": "string" | |
| } | |
| } | |
| ], | |
| "responses": { | |
| "200": { | |
| "description": "Successful response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "type": "object" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } | |
| } |
In the AI Agent, go to actions, and we’re presented with a few options. We want to select the OpenAPI 3.0 specified tool:
Give it a name and description (optional):
Then next we’ll want to select the connection we created earlier for the Companies House API Key and pasting in the OpenAPI spec from above:
Next and ‘Create Tool’ to finish. That’s it! Now we’re ready to try this out!
Testing the API tool
I have added a simple prompt to my example: “Use the Companies House API action to return relevant information about the company name or number if provided”. When pasting a UK Companies House number, the agent is now able to select the most relevant API operation and make the call, returning the company information. In this instance, it returned Microsoft UK HQ.
And again, querying the agent for which persons have significant control of the company – the agent can find the relevant API operation from the tool to return the information:
You may be wondering how we can confirm that the action is actually being used and not just the language model’s trained knowledge. Firstly, you will see in the playground that the agent briefly calls OpenAPI before returning the data. Secondly, you will also notice a tools sub icon next to the token usage, which shows a numeric value of 1, confirming that the tool was used.
Additionally, if we click on the thread logs and go to the metadata tab, we are able to explore the logs in more detail to confirm that the tool was called. We can even see which API operation the agent selected to make the call and return the data. In this case, it used get company profile
Closing thoughts
I really love the fact that you can embed this kind of action directly into agents without needing any additional middleware to handle it. Obviously, the UK Companies House register is not the only API where this is a compelling use case. There are many others, both public and private, that may be relevant to your organisation. While calling a Function or a Logic App gives you more flexibility over what the action does, this is a very straightforward way to integrate OpenAPI specifications into your AI agents. It makes multi agent chaining for sub tasks and modular workflows incredibly smooth.
Although the portal was a convenient way to demonstrate this functionality and the Companies House use case, it is limited in terms of how you can invoke and use the agent. The Foundry SDK offers full customisation of response types, functions, and much more. It is currently in preview, but it is clear that this is the direction the team is heading with Foundry.
If you were wondering, Bing Grounding and Bing Custom Search can be unreliable for certain webpages, such as UK government sites. Much of the required information is not rendered in the page source and is hidden behind JavaScript, which is why this approach works so well.